Skip to main content

The SimpleRestJson protocol

Smithy4s provides a custom Json-in/Json-out protocol that smithy services can be annotated with.

Smithy4s comes with opt-in http4s-specific module, that contains functions that are aware of this protocol, and can be used to quickly derive http services and clients.

As for the json aspect of the protocol, jsoniter-scala is used for the (de)serialisation of the http bodies.

Semantics

In this protocol, the values in shapes are bound to http metadata or body according to the specification of the Http Binding traits. However, the @mediaType trait has no incidence, and all bodies (when present) are serialised in JSON.

Example spec

namespace smithy4s.example

use smithy4s.api#simpleRestJson

@simpleRestJson
service HelloWorldService {
version: "1.0.0"
// Indicates that all operations in `HelloWorldService`,
// here limited to the Hello operation, can return `GenericServerError`.
errors: [GenericServerError]
operations: [Hello]
}

@error("server")
@httpError(500)
structure GenericServerError {
message: String
}

@http(method: "POST", uri: "/{name}", code: 200)
operation Hello {
input: Person
output: Greeting
}

structure Person {
@httpLabel
@required
name: String

@httpQuery("town")
town: String
}

structure Greeting {
@required
message: String
}

Supported traits

This protocol and its interpreters, are aware of the following traits provided out of the box:

Decoding and encoding unions

The SimpleRestJson protocol supports 3 different union encodings :

  • tagged (default)
  • untagged
  • discriminated

See the section about unions for a detailed description.