Creating HTTP APIs

Dependencies

First, let's open the build.gradle.kts file and examine added dependencies:

Let's briefly go through these dependencies one by one:

• ktor-server-core-jvm adds Ktor's core components to our project.

• ktor-server-content-negotiation-jvm and ktor-serialization-kotlinx-json-jvm provide a convenient mechanism for converting Kotlin objects into a serialized form like JSON, and vice versa. We will use it to format our APIs output, and to consume user input that is structured in JSON. In order to use ktor-serialization-kotlinx-json, we also have to apply the plugin.serialization plugin.

  plugins { id("io.ktor.plugin") version "2.3.6" }

• ktor-server-netty-jvm adds the Netty engine to our project, allowing us to use server functionality without having to rely on an external application container.

• logback-classic provides an implementation of SLF4J, allowing us to see nicely formatted logs in a console.

• ktor-server-test-host and kotlin-test-junit allow us to test parts of our Ktor application without having to use the whole HTTP stack in the process. We will use this to define unit tests for our project.

Configurations: application.conf and logback.xml

The generated project also includes the application.conf and logback.xml configuration files located in the resources folder:

• application.conf is a configuration file in HOCON format. Ktor uses this file to determine the port on which it should run, and it also defines the entry point of our application.

  ktor { deployment { port = 8080 port = ${?PORT} } application { modules = [ com.example.ApplicationKt.module ] } }

  If you'd like to learn more about how a Ktor server is configured, check out the Configuration in a file help topic.

• logback.xml sets up the basic logging structure for our server. If you'd like to learn more about logging in Ktor, check out the Logging topic.

Source code

The application.conf file configures the entry point of our application to be com.example.ApplicationKt.module. This corresponds to the Application.module() function in Application.kt, which is an application module:

This module, in turn, calls the following extension functions:

• configureRouting is a function defined in plugins/Routing.kt, which currently doesn't do anything:

  fun Application.configureRouting() { routing { } }

  We'll define the routes for customers and orders in the next chapters.

• configureSerialization is a function defined in plugins/Serialization.kt, which installs ContentNegotiation and enables the json serializer:

  fun Application.configureSerialization() { install(ContentNegotiation) { json() } }

Create the Customer model

For our case, a customer should store some basic information in the form of text: a customer should have an id by which we can identify them, a first and last name, and an email address. An easy way to model this in Kotlin is by using a data class:

1. Create a new package named models inside com.example.

2. Create a Customer.kt file in the models package and add the following code:

   package com.example.models import kotlinx.serialization.Serializable @Serializable data class Customer(val id: String, val firstName: String, val lastName: String, val email: String)

   Note that we are using the @Serializable annotation from kotlinx.serialization. Together with its Ktor integration, this will allow us to generate the JSON representation we need for our API responses automatically – as we will see in just a bit.

Create the Customer storage

To not complicate the code, for this tutorial, we'll be using an in-memory storage (i.e. a mutable list of Customers) – in a real application, we would be storing this information in a database so that it doesn't get lost after restarting our application. We can add this line right after the data class declaration in Customer.kt file:

Now that we have a well-defined Customer class and a storage for our customer objects, it's time we create endpoints and expose them via our API!

Define the routing for customers

We want to respond to GET, POST, and DELETE requests on the /customer endpoint. As such, let's define our routes with the corresponding HTTP methods.

1. Create a new package named routes inside com.example.

2. Create a CustomerRoutes.kt file called in the routes package, and fill it with the following:

   package com.example.routes import io.ktor.server.routing.* fun Route.customerRouting() { route("/customer") { get { } get("{id?}") { } post { } delete("{id?}") { } } }

   In this case, we're using the route function to group everything that falls under the /customer endpoint. We then create a block for each HTTP method. This is just one approach how we can structure our routes – when we tackle the Order routes in the next chapter, we will see another approach.

   Notice also how we actually have two entries for get: one without a path parameter, and the other with {id?}. We'll use the first entry to list all customers, and the second entry to display a specific one.

Register the routes

Up until now, we have only defined our routes inside an extension function on Route – so Ktor doesn't know about our routes yet, and we need to register them. Open the plugins/Routing.kt file and add the following code:

As you might remember, the configureRouting function is already invoked in our Application.module() function in Application.kt.

We've now completed the implementation for the customer-related routes in our API. If you would like to validate that everything works right away, you can skip ahead to the chapter Test HTTP endpoints manually. If you can still bear the suspense, we can move on to the implementation of order-related routes.

Create the Order model

The orders we want to store in our system should be identifiable by an order number (which might contain dashes), and should contain a list of order items. These order items should have a textual description, the number of how often this item appears in the order, as well as the price for the individual item (so that we can compute the total price of an order on demand).

Inside the models package, create a new file called Order.kt and fill it with the definition of the two data classes:

We also once again need a place to store our orders. To skip having to define a POST route – something you're more than welcome to attempt on your own using the knowledge from the Customer routes – we will prepopulate our orderStorage with some sample orders. We can again define it as a top-level declaration inside the Order.kt file.

Define the routing for orders

We respond to a set of GET requests with three different patterns:

The first will return all orders, the second will return an order given the id, and the third will return the total of an order (prices of individual OrderItems multiplied by number of each item).

With orders, we're going to follow a different pattern when it comes to defining routes. Instead of grouping all routes under a single route function with different HTTP methods, we'll use individual functions.

Register the routes

Finally, much like the case of customers, we need to register the routes. Hopefully, this makes it clear why grouping routes makes more sense as the number of routes grows. Still in plugins/Routing.kt, add the routes for orders as follows:

Now that we have everything wired up, we can finally start testing our application, and see if everything works as we would expect it to!

Create a customer HTTP test file

Let's create a new CustomerTest.http file in the project root:

Inside this file, we have now specified a bunch of HTTP requests using all the supported HTTP methods of our API. IntelliJ IDEA now allows us to run each of these requests individually or all together. To really see what's going on, let's run them individually. But first, we need to make sure our API is actually reachable!

Run API server

Before we can run a request, we need to first start our API server. Open the Application.kt file and click on the Run icon in the gutter:

Once the server is up and running, we can execute each request by using the Run icon in the gutter:

If everything is correct, we should see the output in the Run tool window:

Order endpoints

For the order endpoints, we can follow the same procedure: we create a new file called OrderTest.http in the root of our project and fill it with some HTTP requests:

Running these requests just as the ones before, we should see the expected output – list of orders, information about one order, and the total of the order.

Feature requests

• Authentication: currently, the API is open to whomever would like to access it. If you want to restrict access, have a look at Ktor's support for JWT and other authentication methods.

• Learn more about route organization! If you'd like to learn about different ways to organize your routes with Ktor, check out the Routing topic.

• Persistence! Currently, all customers and orders vanish when we stop our application, as we are only storing them in an in-memory storage. You could try integrating your application with a database like PostgreSQL or MongoDB, using one of the plenty projects that allow database access from Kotlin, like Exposed or KMongo.

• Integrate with a client! Now that we are exposing data, it would make sense to explore how this data can be consumed again! Try writing an API client using the Ktor HTTP client, for example, or try accessing it from a website using JavaScript or Kotlin/JS!

  To make sure your API works nicely with browser clients, you should also set up a policy for Cross-Origin Resource Sharing (CORS). The simplest and most permissive way to do this with Ktor would be by adding the following snippet to the top of Application.module():

  install(CORS) { anyHost() }