19. An HTTP API with Tapir and http4s

By the end of this chapter you’ll be able to book a table with curl. Three requests will work: one that lists tonight’s bookings, one that makes a booking and one that looks a booking up by name. A request that can’t be met gets an answer saying what’s wrong with it.

The server is http4s, an HTTP library built on Cats Effect and fs2 whose own server is called Ember. On top of it I use Tapir, where each endpoint is a value that describes its path, its input and its answers. Tapir produces both the http4s routes and the documentation from that value, so the paths and shapes in the documentation can’t fall behind the code.

19.1. One endpoint

Add four libraries to the service subproject’s list in build.sbt, after the line for Logback:

      "com.softwaremill.sttp.tapir" %% "tapir-http4s-server" % "1.14.1",
      "com.softwaremill.sttp.tapir" %% "tapir-json-circe" % "1.14.1",
      "com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-bundle" % "1.14.1",
      "org.http4s" %% "http4s-ember-server" % "0.23.38",

The server will read its port from the configuration, so add port = 8080 as the last line of application.conf and give AppConfig a field for it:

case class AppConfig(
    restaurant: String,
    journal: String,
    storeDelay: FiniteDuration,
    port: Int
) derives ConfigReader

Then create api.scala in service/src/main/scala:

package fullybooked

import io.circe.Codec
import sttp.tapir.*
import sttp.tapir.json.circe.*

case class BookingView(name: String, size: Int, table: Int, time: String, status: String)
    derives Codec.AsObject,
      Schema

object BookingView:
  def of(booking: Booking): BookingView =
    BookingView(
      booking.party.name,
      booking.party.size,
      booking.table.number,
      booking.time.toString,
      describe(booking.status)
    )

val listEndpoint =
  endpoint.get
    .in("bookings")
    .out(jsonBody[List[BookingView]])
    .description("Every booking for tonight")

The class BookingView is a booking as the API shows it, in five plain fields. I keep these types apart from the model. A Booking holds an opaque Phone and a Status with data in two of its cases. The model should stay free to change without every client of the API noticing. The derives clause on BookingView asks circe, a JSON library, for a Codec.AsObject that can encode and decode the class. It asks Tapir for a Schema, which describes the class in the documentation.

The value listEndpoint describes one request, a GET to /bookings that’s answered with a list of BookingViews as JSON. I’ve left the compiler to work out its type, because it’s long. Among other things the type records what the endpoint takes in, what it answers with when it fails and what it answers with when it succeeds. Here those are nothing, nothing and the list.

The code that produces the list goes in a second file, routes.scala, beside the first:

package fullybooked

import cats.effect.IO
import sttp.capabilities.fs2.Fs2Streams
import sttp.tapir.server.ServerEndpoint

def bookingRoutes(bookings: Bookings): List[ServerEndpoint[Fs2Streams[IO], IO]] =
  List(
    listEndpoint.serverLogicSuccess(_ => bookings.all.map(_.map(BookingView.of)))
  )

Calling serverLogicSuccess on an endpoint gives it a function that takes the endpoint’s input and returns an IO of its output. The result is a ServerEndpoint: the description together with the code that answers the request. Its two type parameters say that our endpoints may use fs2’s streams, though they don’t, and that they run in IO. The Bookings passed in is the class from chapter 14 that keeps its list in a Ref.

The third file, server.scala, goes in the same directory:

package fullybooked

import cats.effect.{IO, IOApp}
import com.comcast.ip4s.{ipv4, Port}
import org.http4s.ember.server.EmberServerBuilder
import org.http4s.server.middleware.Logger
import sttp.tapir.server.http4s.Http4sServerInterpreter
import sttp.tapir.swagger.bundle.SwaggerInterpreter

object Server extends IOApp.Simple:
  def run: IO[Unit] =
    for
      config <- loadConfig
      port <- IO.fromOption(Port.fromInt(config.port))(
        IllegalArgumentException(s"${config.port} isn't a port")
      )
      bookings <- Bookings.starting(List())
      routes = bookingRoutes(bookings)
      docs = SwaggerInterpreter().fromServerEndpoints[IO](routes, config.restaurant, "0.1.0")
      app = Http4sServerInterpreter[IO]().toRoutes(routes ++ docs).orNotFound
      _ <- EmberServerBuilder
        .default[IO]
        .withHost(ipv4"0.0.0.0")
        .withPort(port)
        .withHttpApp(Logger.httpApp(logHeaders = false, logBody = false)(app))
        .build
        .useForever
    yield ()

The run method loads the configuration, makes an empty Bookings and gets the routes for it. Tapir’s SwaggerInterpreter writes documentation for those routes, which comes back as more endpoints to serve. Http4sServerInterpreter then turns the lot into an http4s application, with orNotFound answering 404 for any other path.

Ember serves that application on every network interface, at the port from the configuration. The ipv4 in front of "0.0.0.0" is a string interpolator like s. It checks the address when the code compiles, so a mistyped address is a compile error. A port that arrives as an Int at run time can’t be checked that way. Port.fromInt returns an Option[Port], which is None for a number that can’t be a port. IO.fromOption turns a None into a failed IO, so a bad port stops the service at start-up. Before the application is handed to Ember it’s wrapped in Logger.httpApp to log each request and response. The server that build returns is a Resource, and useForever keeps it open until the program is stopped.

Start the server:

$ sbt "service/runMain fullybooked.Server"
INFO  EmberServerBuilderCompanionPlatform: Ember-Server service bound to address: [::]:8080
INFO  Logger: HTTP/1.1 GET /bookings
INFO  Logger: HTTP/1.1 200 OK

The [::] in the first log line is how Java reports a socket that listens on every interface. The lines after it appear as requests arrive. In a second terminal, ask for the bookings:

$ curl localhost:8080/bookings
[]

Then open http://localhost:8080/docs in a browser. The page lists the endpoint. Click on it for its description, the shape of a BookingView and a button that sends the request. Behind the page is a document in the OpenAPI format that other tools can read:

$ curl localhost:8080/docs/docs.yaml
openapi: 3.1.0
info:
  title: Fully Booked
  version: 0.1.0
paths:
  /bookings:
    get:
      description: Every booking for tonight
      operationId: getBookings
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BookingView'
...

19.2. Taking a booking

Stop the server with Ctrl+C. sbt may print an exception about the way the program ended. You can ignore it. The other two endpoints need a status code in their types, so add import sttp.model.StatusCode under the import of Codec in api.scala. Then add this to the end of the file:

case class NewBooking(name: String, size: Int, time: String, phone: Option[String])
    derives Codec.AsObject,
      Schema

case class Problems(problems: List[String]) derives Codec.AsObject, Schema

type Refusal = (StatusCode, Problems)

val createEndpoint =
  endpoint.post
    .in("bookings")
    .in(jsonBody[NewBooking])
    .out(statusCode(StatusCode.Created))
    .out(jsonBody[BookingView])
    .errorOut(statusCode)
    .errorOut(jsonBody[Problems])
    .description("Book a table")

val findEndpoint =
  endpoint.get
    .in("bookings" / path[String]("name"))
    .out(jsonBody[BookingView])
    .errorOut(statusCode)
    .errorOut(jsonBody[Problems])
    .description("The booking under one name")

A client sends a NewBooking, in which size is a number and phone can be left out. When a request fails, the client gets back Problems, a list of messages. A Refusal is a tuple of a status code and the Problems to send with it.

In the two endpoints, each in adds an input, which can be a piece of the path or the body. "bookings" / path[String]("name") is two pieces of path, the second of which is handed to our code as a String. Among the outputs, statusCode(StatusCode.Created) fixes the status of a successful POST at 201. The two errorOut lines say that a failure is a status code followed by Problems as JSON.

Replace everything in routes.scala with the logic for all three:

package fullybooked

import cats.effect.IO
import sttp.capabilities.fs2.Fs2Streams
import sttp.model.StatusCode
import sttp.tapir.server.ServerEndpoint

def refusal(status: StatusCode, problems: List[String]): Refusal = (status, Problems(problems))

def create(bookings: Bookings, request: NewBooking): IO[Either[Refusal, BookingView]] =
  val asText =
    BookingRequest(request.name, request.size.toString, request.time, request.phone.getOrElse(""))
  validate(asText) match
    case Left(errors) =>
      IO.pure(Left(refusal(StatusCode.BadRequest, errors.toList.map(explain))))
    case Right((party, time)) =>
      bookings
        .reserve(party, time)
        .map:
          case Right(booking) => Right(BookingView.of(booking))
          case Left(error) => Left(refusal(StatusCode.Conflict, List(explain(error))))

def find(bookings: Bookings, name: String): IO[Either[Refusal, BookingView]] =
  bookings.all.map: all =>
    findBooking(name, all)
      .map(BookingView.of)
      .toRight(refusal(StatusCode.NotFound, List(s"no booking under $name")))

def bookingRoutes(bookings: Bookings): List[ServerEndpoint[Fs2Streams[IO], IO]] =
  List(
    listEndpoint.serverLogicSuccess(_ => bookings.all.map(_.map(BookingView.of))),
    createEndpoint.serverLogic(request => create(bookings, request)),
    findEndpoint.serverLogic(name => find(bookings, name))
  )

The function create turns the NewBooking into the four strings of a BookingRequest and hands them to validate, the function that checked the command line’s four strings in chapter 9. A request that fails validation is the client’s mistake and gets 400 with every problem listed. One that’s well formed but refused by reserve, usually because the tables are taken, gets 409. In find, a name with no booking gets 404.

Where serverLogicSuccess took a function with no error value to return, serverLogic wants one that returns an IO of an Either, with the endpoint’s error type on the left. create and find are ordinary functions of that shape, so they can be tested with no server running. The test file below has a helper called answers that sends a list of requests through create one after another. Its traverse works on IO as it did on Either in chapter 11. It keeps the name from each success and the status code from each refusal. Create api.test.scala in service/src/test/scala:

package fullybooked

import cats.effect.unsafe.implicits.global
import cats.syntax.all.*
import sttp.model.StatusCode

class ApiTests extends munit.FunSuite:
  def answers(requests: List[NewBooking]): List[Either[StatusCode, String]] =
    val program =
      for
        bookings <- Bookings.starting(regulars)
        results <- requests.traverse(request => create(bookings, request))
      yield results.map(result => result.left.map(refused => refused(0)).map(view => view.name))
    program.unsafeRunSync()

  test("a good request is booked"):
    assertEquals(answers(List(NewBooking("Ibrahim", 7, "20:00", None))), List(Right("Ibrahim")))

  test("a request that fails validation is a 400 listing every problem"):
    val bad = NewBooking("", 7, "8pm", Some("ask for Dev"))
    assertEquals(answers(List(bad)), List(Left(StatusCode.BadRequest)))
    val program = Bookings.starting(regulars).flatMap(bookings => create(bookings, bad))
    assertEquals(program.unsafeRunSync().left.map(refused => refused(1).problems.size), Left(3))

  test("the second party after the last table gets a 409"):
    val both = List(
      NewBooking("Ibrahim", 7, "20:00", None),
      NewBooking("Castellanos", 8, "20:00", None)
    )
    assertEquals(answers(both), List(Right("Ibrahim"), Left(StatusCode.Conflict)))

  test("a name with no booking is a 404"):
    val program = Bookings.starting(regulars).flatMap(bookings => find(bookings, "Smith"))
    assertEquals(program.unsafeRunSync().left.map(refused => refused(0)), Left(StatusCode.NotFound))
$ sbt "service/test fullybooked.ApiTests"
[info] Passed: Total 4, Failed 0, Errors 0, Passed 4
[success] elapsed time: 2 s

Start the server again and book a table. If typing JSON into a terminal doesn’t appeal, or you’re on Windows where the quoting is different, the page at /docs will send the same requests.

$ curl -d '{"name":"Hughes","size":4,"time":"18:30"}' -H 'Content-Type: application/json' localhost:8080/bookings
{"name":"Hughes","size":4,"table":3,"time":"18:30","status":"confirmed"}

The -d option supplies a body and makes the request a POST. Next, send a request with two things wrong, adding -i to show the status line and headers of the answer. I’ve left the Date header out of the listing:

$ curl -i -d '{"name":"","size":4,"time":"7pm"}' -H 'Content-Type: application/json' localhost:8080/bookings
HTTP/1.1 400 Bad Request
Connection: keep-alive
Content-Type: application/json
Content-Length: 79

{"problems":["we need a name for the booking","'7pm' isn't a time, try 19:30"]}

Book the Mbekis in for eight people at 20:00 in the same way as the Hugheses. Then try the Tanakas, who want the same table. -w '\n%{http_code}\n' prints the status on a line of its own after the body:

$ curl -d '{"name":"Tanaka","size":8,"time":"20:00"}' -H 'Content-Type: application/json' -w '\n%{http_code}\n' localhost:8080/bookings
{"problems":["no table for 8 is free at 20:00"]}
409

The Tanakas get a 409 because the Mbekis have the last table for eight. If the two requests had arrived at the same moment, one party would still have got the table and the other a 409. The check and the save in Bookings.reserve are one atomic step.

Look a booking up under a name that has one, and then under a name that hasn’t:

$ curl -w '\n%{http_code}\n' localhost:8080/bookings/Mbeki
{"name":"Mbeki","size":8,"table":6,"time":"20:00","status":"confirmed"}
200
$ curl -w '\n%{http_code}\n' localhost:8080/bookings/Smith
{"problems":["no booking under Smith"]}
404

Send a body in which the size isn’t a number:

$ curl -d '{"name":"Tanaka","size":"eight","time":"20:00"}' -H 'Content-Type: application/json' -w '\n%{http_code}\n' localhost:8080/bookings
Invalid value for: body (Int at 'size')
400

The body isn’t a NewBooking, since "eight" isn’t a number, so Tapir answers 400 by itself. The message is Tapir’s and it’s plain text, where our own failures are JSON. If a client ever reports an error message that you can’t find in your own code, this is one place to look. Tapir lets you replace its answer with one of your own, which I’d do for a public API.

19.3. Middleware

http4s calls Logger.httpApp a middleware: a function that takes an application and returns another, which does something before or after it passes each request on. Because the logger wraps the whole application, the log shows the requests for the documentation and the ones that ended in 404, as well as those for bookings.

I use a middleware when something should happen to every request whatever the endpoint. http4s has them for timing requests out and for CORS headers, among others. Chapter 22 adds two when it gets the service ready to deploy.

19.4. Exercises

Solutions are in the book’s downloadable code, under ch19/exercises.

  1. Add DELETE /bookings/{name}, which removes a booking. It should answer 204 with no body, or 404 if there was no booking under that name. Bookings will need a cancel method, and endpoint.delete starts the description.

  2. Let GET /bookings?size=4 list only the parties of four or more. query[Option[Int]]("size") describes an optional query parameter.

  3. A party of nine gets 409, as though the restaurant were full. It can never be seated, so 400 would be a better answer. Write statusFor(error: BookingError): StatusCode and use it in create.

  4. Add GET /tables, which lists the restaurant’s tables. Table lives in core, which knows nothing about JSON, so it will need a view class of its own.

  5. Open /docs after each of the exercises above and find what changed.