Ktor 1.3 Release

Sergey Mashkov

Ktor 1.3 was released recently, and we’re happy to share the details with you in this blog post.

13release-01

Ktor consists of two parts: the server engine and a flexible asynchronous HTTP client. The current release focuses mainly on the HTTP client. Here you can find the complete changelog for this release.

The client is a multiplatform library that supports JVM, JS, Android, and iOS and is now often used in cross-platform mobile applications. Our main goal for the next releases is to make the server engine multiplatform, too.

The other areas we’re going to work on are:

  • Improving integration with the kotlinx.serialization library.
  • Supporting CIO (coroutines-based I/O client engine) on Kotlin/Native to make it a default multiplatform engine used in HttpClient.

If you currently use Ktor, either server or HttpClient, or have tried it at some point before, please take part in the following survey:

Take part in the survey

We’d be really grateful if you could share your experience with us!

Now let’s dive into the details of what Ktor 1.3 release brings.

HttpClient

Introducing HttpStatement

In the previous Ktor versions, you needed to explicitly close the HttpResponse. However, that was often a source of confusion. We’ve found a lot of cases where someone had forgotten to close the HttpResponse, even in simple examples, and got memory leaks because of it. To improve this situation we introduce the incompatible change in Ktor 1.3: HttpResponse no longer implements the Closeable interface. Thus the 1.3.0 Ktor release is not backwards compatible with the previous version Ktor 1.2.X.

HttpResponse is in-memory by default; and there is no need to close it anymore:

If you need to handle streaming or big responses, use the new HttpStatement class. HttpStatement doesn’t perform any network requests until you explicitly call the execute method:

For instance, you can read the data by chunks:

Configuring Proxy

The HttpClient adds experimental support for proxy. If you need to send requests under proxy, you can configure its address in the corresponding parameters:

Note that because of the platform restrictions it’s only supported for JVM and Native targets (except WatchOS) and isn’t supported for JavaScript. More details on how to configure it for different platforms can be found here.

Using NSURLSession for iOS engine

The iOS engine now provides a way to configure NSURLSession:

NSURLSession is a default API to interact with HTTP / HTTPS protocols on iOS, so now you can use it to tweak all the iOS-related settings.

Working with JSON improved

The following changes are supported both on HttpClient and server, so far in an experimental state.

Simplified collections serialization in JSON

In the previous Ktor versions, you needed to register auxiliary types for serializing collections. Now this process is simplified: JsonFeature handles collection types without additional configuration. And all the related functions like setMapper, setListMapper, register are now deprecated.

There is no need to register List<User> in JsonFeature anymore:

The same applies when working with JSON on a server, you can specify the collection types with the expected generic arguments when receiving the content:

kotlinx.serialization DSL

Ktor now supports a way to construct a JSON body using the kotlinx.serialization DSL:

To use it on a client, install JsonFeature and add the ktor-client-serialization dependency. On the server, use the SerializationConverter.

Migration Steps

To migrate your Ktor application to the new version, you’ll need to:

  • Update all your usages of HttpResponse: simply remove the close calls, and use HttpStatement when needed.
  • Update the imports. The kotlinx.io dependency has been removed, so you’ll need to replace imports in the following way:
    • import kotlinx.io. -> import io.ktor.utils.io.
    • import kotlinx.coroutines.io. -> import io.ktor.utils.io.

Note that there’s no binary compatibility with 1.2.x, so if you use any external Ktor features you’ll need to recompile them against the latest version. Also, make sure that you’re using 5.4.1+ Gradle metadata version.

Thank you for reading this and don’t forget to take the survey!

Take part in the survey

Comments below can no longer be edited.

7 Responses to Ktor 1.3 Release

  1. Karthick Ramanathan says:

    January 29, 2020

    Please give us a Udemy or Udacity tutorial for ktor

    • Jose A Perez says:

      February 19, 2020

      I truly agree!

  2. Máté Herber says:

    January 29, 2020

    I think it would be great to split ktor client and server completely both GitHub and documentation wise. Also maybe rename the client library. At the current state it is really hard to find StackOverflow questions / GitHub issues that are relevant.

  3. Carson Holzheimer says:

    January 30, 2020

    Agreed. The docs for mobile client are hard to follow

  4. Christian says:

    January 30, 2020

    Why don’t you follow semantic versioning? It would be useful, if the version number would carry any meaning besides “something is new”.

  5. Dimitar says:

    January 30, 2020

    What confuses me about Ktor is the lack of examples of completely designed big application.
    The one-liners and one-file-holds-them-all examples may be convenient to show how to do something. Great for homework tasks…
    But when team of people work on same application, whey split the functionality in many files, the logic cannot fit in one screen lambda expression, there are different layers, separate views (handled by designers not programmers)…
    Where we could find such high level examples/best practices?

  6. Jose A Perez says:

    February 19, 2020

    a tutorial for Android development would be great,