Building a REST API with Scala

Analogy categoryAnalogies

Choosing an HTTP Toolkit

Three toolkits dominate Scala REST API development: Akka HTTP, now under the Apache Pekko umbrella after Akka's license change, which layers a routing DSL over the actor system and suits teams already using Akka for other concurrency needs; Play Framework, a batteries-included MVC framework with built-in templating, hot-reload, and a gentler learning curve for teams coming from Rails or Spring MVC; and http4s, a purely functional library built on cats-effect that models an HTTP server as a function Request => F[Response], appealing to teams already invested in the Cats/Cats Effect ecosystem. The choice mostly comes down to how comfortable the team already is with tagless-final/effect-system style code — http4s and its ZIO-based cousin, zio-http, demand more functional programming fluency but reward you with more composable, testable services.

🏏

Cricket analogy: It's like choosing a bowling attack: Akka HTTP is the express pacer, actor concurrency you already trust from other parts of the innings, Play is the reliable all-rounder who does a bit of everything with minimal fuss, and http4s is the crafty leg-spinner that needs more skill to use well but is devastating in the right hands.

Defining Routes and JSON Codecs

Model request and response payloads as immutable case classes and derive JSON codecs automatically rather than hand-writing serialization — with circe, io.circe.generic.semiauto.deriveCodec[User] generates an Encoder[User] and Decoder[User] from the case class's field names and types, so a change to the case class shape is enforced consistently across every endpoint that uses it. Routes then become pattern matches on HTTP method and path: an http4s HttpRoutes[F] is built with case GET -> Root / "users" / IntVar(id) => ..., extracting the id path segment as a typed Int directly in the match, and a case req @ POST -> Root / "users" => req.as[CreateUserRequest].flatMap(...) decodes the JSON body straight into your case class, failing with a 400 automatically if the body doesn't match the expected shape.

🏏

Cricket analogy: It's like a scorecard app that auto-generates the printed scorecard format directly from the raw ball-by-ball data model, so if you add a new stat field like 'dot ball percentage' it appears consistently everywhere — circe's deriveCodec auto-generates JSON serialization from a case class the same way, keeping every endpoint in sync.

scala

import cats.effect._
import io.circe.generic.semiauto._
import io.circe.{Decoder, Encoder}
import io.circe.syntax._
import org.http4s._
import org.http4s.dsl.io._
import org.http4s.circe._

final case class CreateUserRequest(name: String, email: String)
final case class User(id: Long, name: String, email: String)

object CreateUserRequest {
  implicit val decoder: Decoder[CreateUserRequest] = deriveDecoder
}
object User {
  implicit val encoder: Encoder[User] = deriveEncoder
}

class UserRoutes(repo: UserRepository) {
  val routes: HttpRoutes[IO] = HttpRoutes.of[IO] {
    case GET -> Root / "users" / IntVar(id) =>
      repo.find(id).flatMap {
        case Some(user) => Ok(user.asJson)
        case None       => NotFound(s"User $id not found")
      }

    case req @ POST -> Root / "users" =>
      for {
        body <- req.as[CreateUserRequest]
        user <- repo.create(body.name, body.email)
        resp <- Created(user.asJson)
      } yield resp
  }
}

Handling Errors and Validation

Push domain errors through a typed channel rather than exceptions: have your service layer return EitherT[F, DomainError, A], or a ZIO effect typed as ZIO[R, DomainError, A], and centralize the mapping from DomainError subtypes to HTTP status codes in one place, like a single errorToResponse function, so a UserNotFound always becomes a 404 and a DuplicateEmail always becomes a 409, regardless of which endpoint triggered it. For input validation where you want to report every problem at once instead of stopping at the first, like 'email is invalid' and 'password too short' in the same response, use cats.data.Validated, or its parallel-friendly cousin ValidatedNel, with mapN, which accumulates errors across independent checks instead of short-circuiting like Either's flatMap does.

🏏

Cricket analogy: It's like the ICC maintaining one central table mapping specific offenses, ball tampering, dissent, to specific penalties, suspension length, so any umpire anywhere applies the same sanction — centralizing DomainError-to-HTTP-status mapping in one function works the same way, keeping responses consistent across every endpoint.

Don't scatter status-code decisions across every route handler by matching on error subtypes inline — it's easy for one endpoint to return 400 for a validation failure while another returns 422 for the same DomainError type. Centralize the mapping once and reuse it everywhere.

Testing and Deploying the API

Write unit tests for your service and repository layers with MUnit or ScalaTest, mocking dependencies with simple hand-written test doubles, since Scala's structural typing and trait-based DI make this easy without a mocking framework, and write route-level integration tests using http4s' Client bound directly to your HttpRoutes in-memory, no real socket needed, to assert on status codes and JSON bodies for real HTTP semantics. For deployment, package the service as a self-contained artifact with sbt-native-packager, producing a Docker image or a native executable, or sbt-assembly's fat JAR, configure it with application.conf, Typesafe Config, so environment-specific settings like database URLs come from environment variables at container start, and run it behind a reverse proxy like nginx or an API gateway that handles TLS termination and rate limiting.

🏏

Cricket analogy: It's like a team running throwdowns in the nets, unit tests with mocked dependencies, before playing a full practice match at the actual ground with real conditions, integration tests against real HTTP routes — both matter, but they catch different kinds of problems.

Pick http4s, Akka/Pekko HTTP, or Play based on the team's FP fluency and existing stack.
Derive JSON codecs from case classes (e.g., circe's deriveCodec) so serialization tracks your data model automatically.
Define routes as pattern matches on HTTP method and path, decoding bodies into typed case classes.
Return typed domain errors (Either/ZIO) and centralize their mapping to HTTP status codes in one place.
Use cats.data.Validated to accumulate multiple validation errors instead of failing fast like Either.
Test routes in-memory via http4s' Client bound to HttpRoutes, avoiding real sockets in CI.
Deploy with sbt-native-packager/Docker and externalize config through environment variables.