smithy4s

1. Define API Contract

Start by defining your API in Smithy, a concise, readable, language-agnostic format.

Smithy is protocol-agnostic, which means that you can use it to describe operations regardless of serialisation/transport.

Smithy provides core semantics to define data types, operations and services. It also provides a powerful and extensible annotation mechanism, called traits to tie those definitions to protocols or validation rules.

Smithy comes with a standard library of protocol-related traits (http/json/xml).

$version: "2.0"

namespace smithy4s.hello

service AdminService {
    operations: [
        GetUser
    ]
}

@http(method: "GET", uri: "/user/{id}")
operation GetUser {
    input := {
        @required
        @httpLabel
        id: String
    }

    output: User
}

structure User {
    @required
    firstName: String

    @required
    lastName: String
}

2. Implement Generated Interface

Smithy4s uses the Smithy model you define to generate Scala code, including an interface that represents the service. This interface contains one method per service operation.

object AdminServiceImpl extends AdminService[IO] {
  def getUser(id: String): IO[User] = ???
}

3. Transform Into HttpRoutes

Passing your service implementation to the SimpleRestJsonBuilder gives you an HttpRoutes instance that handles HTTP routing and JSON serialization/deserialization.

val routes: Resource[IO, HttpRoutes[IO]] =
  SimpleRestJsonBuilder.routes(AdminServiceImpl).resource