The authority to use to access the endpoints

Format of the response entity carrying the client errors.

Convert the ClientErrors type into the endpoints4s internal client error type

Convert the endpoints4s internal client error type into the ClientErrors type

The scheme to use to access the endpoints

Format of the response entity carrying the server error.

Convert the ServerError type into the endpoints4s internal server error type

Convert the endpoints4s internal server error type into the ServerError type

Add the provided headers to the request.

Add the provided queryString to the request.

Add the provided headers to the response.

Note that if the response describes a choice of several possible responses (resulting from the orElse operation), the headers will be added to all the possible responses.

A JSON schema for sequences

Bad Request (400) response, with an entity of type ClientErrors.

A JSON schema for type BigDecimal

A JSON schema for type BigDecimal where certain properties, such as minimum, maximum, etc. are set.

A JSON schema for type Boolean

Query string parameter containing a Boolean value

A JSON schema for type Byte

Chains the two paths

Alternative between two possible request entities, differentiated by the Content-Type header

Alternative between two possible choices of responses.

Server interpreters construct either one or the other response. Client interpreters accept either one or the other response. Documentation interpreters list all the possible responses.

The JSON schema of a coproduct made of the given alternative tagged records

Response used by endpoints4s when decoding a request fails.

The provided implementation forwards to badRequest.

Concatenates two QueryStrings

Default discriminator field name for sum types.

It defaults to "type", but you can override it twofold: - by overriding this field you can change default discriminator name algebra-wide - by using withDiscriminator you can specify discriminator field name for specific sum type

A JSON schema for type String

Helper method to perform DELETE request

A JSON schema for type Double

Codec for query string parameters of type Double

Path segment codec for type Double

A JSON schema for type Double where certain properties, such as minimum, maximum, etc. are set.

An ISO 8601 duration

The JSON schema of a record with no fields

• Encoder interpreters produce an empty JSON object,
• Decoder interpreters fail if the JSON value is not a JSON object,
• Documentation interpreters produce the JSON schema of a JSON object schema with no properties.

Empty request -- request without a body. Use description of endpoints4s.algebra.Endpoints#endpoint to document an empty body.

Ignore headers

• Server interpreters don’t try to parse any information from the request headers,
• Client interpreters supply no specific headers

Use description of endpoints4s.algebra.Endpoints#endpoint to document empty headers.

Empty response entity

• Server interpreters produce no response entity,
• Client interpreters ignore the response entity.

No particular response header.

• Client interpreters should ignore information carried by response headers.

Override this method to customize the behaviour of encoders produced by optFieldWithDefault when encoding a field value that corresponds to the specified default value. By default, the default values are included.

As an example, consider the following Scala class and instances of it.

case class Book(
  name: String,
  availableAsEBook: Boolean = false
)

val book1 = Book("Complete Imaginary Works", false)
val book2 = Book("History of Writing", true)

With encodersSkipDefaultValues = false (which is the default), the field is always encoded, regardless of whether it is also the default value. This makes encoding performance predictable, but results in larger and more complicated encoded payloads:

{ "name": "Complete Imaginary Works", "availableAsEBook": false }
{ "name": "History of Writing", "availableAsEBook": true }

With encodersSkipDefaultValues = true, the field is skipped if its value if also the field's default value. This means encoding can be slower (since potentially expensive equality check needs to be performed), but the encoded payloads are smaller and simpler:

{ "name": "Complete Imaginary Works" }
{ "name": "History of Writing", "availableAsEBook": true }

Define an HTTP endpoint

Promotes a schema to an enumeration.

• Decoder interpreters fail if the input value does not match the encoded values of any of the possible values,
• Encoder interpreters never fail, even if the value is not contained in the set of possible values,
• Documentation interpreters enrich the JSON schema with an enum property listing the possible values.

The JSON schema of a record with a single field name of type A

• Encoder interpreters produce a JSON object with one property of the given name,
• Decoder interpreters fail if the JSON value is not a JSON object, or if it doesn’t contain the name property, or if the property has an invalid value (according to its tpe),
• Documentation interpreters produce the JSON schema of a JSON object schema with one required property of the given name.

A JSON schema for type Float

A JSON schema for type BigDecimal where certain properties, such as minimum, maximum, etc. are set.

Helper method to perform GET request

An ISO 8601 date-time in UTC

Convenient constructor for enumerations represented by int values.

A JSON schema for type Int

Ability to define Int query string parameters

Path segment codec for type Int

A JSON schema for type Int where certain properties, such as minimum, maximum, etc. are set.

Internal Server Error (500) response, with an entity of type ServerError.

Request with a JSON body, given an implicit JsonRequest[A]

• Server interpreters accept requests with content-type application/json and reject requests with an incorrect content-type.
• Client interpreters supply content-type application/json

Defines a Response[A] given an implicit JsonResponse[A]

Provides xmap and xmapPartial operations.

Captures a lazy reference to a JSON schema currently being defined:

case class Recursive(next: Option[Recursive])
val recursiveSchema: Record[Recursive] =
  lazyRecord("Rec") {
    optField("next")(recursiveSchema)
  }.xmap(Recursive(_))(_.next)

Interpreters should return a JsonSchema value that does not evaluate the given schema unless it is effectively used.

Captures a lazy reference to a JSON schema currently being defined:

case class Recursive(next: Option[Recursive])
val recursiveSchema: Record[Recursive] = (
  optField("next")(lazyRecord(recursiveSchema, "Rec"))
).xmap(Recursive)(_.next)

Interpreters should return a JsonSchema value that does not evaluate the given schema unless it is effectively used.

A lazy JSON schema that can references schemas currently being defined:

case class Recursive(next: Option[Recursive])
val recursiveSchema: JsonSchema[Recursive] = lazySchema("Rec")(
  optField("next")(recursiveSchema)
).xmap(Recursive)(_.next)

Interpreters should return a JsonSchema value that does not evaluate the given schema unless it is effectively used.

Captures a lazy reference to a JSON schema currently being defined.

Interpreters should return a JsonSchema value that does not evaluate the given schema unless it is effectively used.

Captures a lazy reference to a JSON schema currently being defined.

Interpreters should return a JsonSchema value that does not evaluate the given schema unless it is effectively used.

A schema for a statically known value.

• Decoder interpreters first try to decode incoming values with the given tpe schema, and then check that it is equal to the given value,
• Encoder interpreters always produce the given value, encoded according to tpe,
• Documentation interpreters enrich the JSON schema with a const property documenting its only possible value (or an enum property with a single item).

This is useful to model schemas of objects containing extra fields that are absent from their Scala representation. For example, here is a schema for a GeoJSON point:

case class Point(lon: Double, lat: Double)
val pointSchema = (
  field("type")(literal("Point")) zip
  field[(Double, Double)]("coordinates")
).xmap(Point.tupled)(p => (p.lon, p.lat))

A JSON schema for type Long

Query string parameter containing a Long value

Path segment codec for type Long

A JSON schema for type Long where certain properties, such as minimum, maximum, etc. are set.

Map the inner documentation of the endpoint to new documentation.

Map the inner request of the endpoint to a new request. This is for example useful to add Auth headers to an existing endpoint.

Map the inner response of the endpoint to a new response. This is for example useful so you can add error handling to an existing endpoint.

A JSON schema for maps with string keys

Annotates the enumeration JSON schema with a name

Annotates the record JSON schema with a name

Annotates the tagged JSON schema with a name

An ISO8601 date-time

OK (200) Response with the given entity

The JSON schema of a record with a single optional field name of type A

• Encoder interpreters can omit the field or emit a field with a null value,
• Decoder interpreters successfully decode None if the field is absent or if it is present but has the value null. They fail if the field is present but contains an invalid value,
• Documentation interpreters produce the JSON schema of a JSON object with an optional property of the given name.

The JSON schema of a record with a single optional field with the given name

• Decoders fallback to the defaultValue if the field is absent from the decoded JSON object. They fail if the field is present but has an invalid value,
• Encoders must emit the field if it is not defaultValue, but can choose to omit it when it has the defaultValue
• Documentation interpreters produce the JSON schema of a JSON object with an optional property of the given name.

Builds a QueryString with one optional parameter, which has a default value.

Examples:

optQsWithDefault[Int]("page", 1) // optional `page` parameter, with default value 1

An optional request header

Response headers optionally containing a header with the given name.

• Client interpreters should model the header value as Some[String], or None if the response header is missing.
• Server interpreters should produce such a response header.
• Documentation interpreters should document this header.

Make a query string parameter optional:

path / "articles" /? qs[Option[Int]]("page")

• Client interpreters must omit optional query string parameters that are empty.
• Server interpreters must accept incoming requests whose optional query string parameters are missing, and they must report a failure for incoming requests whose optional query string parameters are present, but malformed,
• Documentation interpreters should mark the parameter as optional.

The JSON schema of a coproduct that share the same parent type and thus can be widened to that parent type

A schema that can be either schemaA or schemaB.

Documentation interpreter produce a oneOf JSON schema. Encoder interpreters forward to either schemaA or schemaB. Decoder interpreters first try to decode with schemaA, and fallback to schemaB in case of failure.

The difference between this operation and the operation orElse on “tagged” schemas is that this operation does not rely on a discriminator field between the alternative schemas. As a consequence, decoding is slower than with “tagged” schemas and provides less precise error messages.

Helper method to perform PATCH request

An empty path.

Useful to begin a path definition:

path / "foo" / segment[Int] /? qs[String]("bar")

Provides xmap and xmapPartial operations.

Helper method to perform POST request

The JSON schema of a record with a single field name of type A with fine control over presence and null

• Encoder interpreters may produce a JSON object with one property of the given name, which can be set to the null value,
• Decoder interpreters successfully decode Absent if the field is absent, Null if it is present but has the value null. They fail if the field is present but contains an invalid value,
• Documentation interpreters produce the JSON schema of a JSON object with an optional property of the given name.

Helper method to perform PUT request

Builds a QueryString with one parameter.

Examples:

qs[Int]("page")            // mandatory `page` parameter
qs[Option[String]]("lang") // optional `lang` parameter
qs[List[Long]]("id")       // repeated `id` parameter

Provides xmap and xmapPartial operations.

Provides xmap and xmapPartial operations.

Provides xmap and xmapPartial operations.

The remaining segments of the path. The String value carried by this Path is still URL-encoded.

Support query string parameters with multiple values:

path / "articles" /? qs[List[Long]]("id")

• Server interpreters must accept incoming requests where such parameters are missing (in such a case, its value is an empty collection), and report a failure if at least one value is malformed.

Request for given parameters

Provides the operations xmap and xmapPartial.

A required request header

Provides the operations xmap and xmapPartial.

Provides ++ operation.

Provides the operations xmap and xmapPartial.

Define an HTTP response

• Server interpreters construct a response with the given status and entity.
• Client interpreters accept a response only if it has a corresponding status code.

Response headers containing a header with the given name.

• Client interpreters should model the header value as String, or fail if the response header is missing.
• Server interpreters should produce such a response header.
• Documentation interpreters should document this header.

Example:

val versionedResource: Endpoint[Unit, (SomeResource, String)] =
  endpoint(
    get(path / "versioned-resource"),
    ok(
      jsonResponse[SomeResource],
      headers = responseHeader("ETag")
    )
  )

Provides xmap operation.

Provides ++ operation.

Provides the operation xmap to the type Response

A path segment carrying an A information

Provides xmap and xmapPartial operations.

Response used by endpoints4s when the business logic of an endpoint fails.

The provided implementation forwards to internalServerError

A path segment whose value is the given segment

Turns a JsonCodec[A] into a Codec[String, A]

Convenient constructor for enumerations represented by string values.

A JSON schema for type String.

Ability to define String query string parameters

Path segment codec for type String

• Server interpreters should return an URL-decoded string value,
• Client interpreters should take an URL-decoded string value.

Provides xmap and xmapPartial operations.

Tags a schema for type A with the given tag name

Request with a String body.

• Server interpreters accept requests with content-type text/plain and reject requests with an incorrect content-type.
• Server interpreters will use the character encoding set in the content-type header to determine how the text is decoded.
• Client interpreters supply content-type text/plain with an explicit character encoding

Text response entity

• Server interpreters produce an HTTP response with a text/plain content type.

A JSON schema for a tuple of 10 elements.

Tuples are represented with JSON arrays, as documented in https://json-schema.org/understanding-json-schema/reference/array.html#tuple-validation.

A JSON schema for a tuple of 11 elements.

Tuples are represented with JSON arrays, as documented in https://json-schema.org/understanding-json-schema/reference/array.html#tuple-validation.

A JSON schema for a tuple of 12 elements.

Tuples are represented with JSON arrays, as documented in https://json-schema.org/understanding-json-schema/reference/array.html#tuple-validation.

A JSON schema for a tuple of 13 elements.

Tuples are represented with JSON arrays, as documented in https://json-schema.org/understanding-json-schema/reference/array.html#tuple-validation.

A JSON schema for a tuple of 14 elements.

Tuples are represented with JSON arrays, as documented in https://json-schema.org/understanding-json-schema/reference/array.html#tuple-validation.

A JSON schema for a tuple of 15 elements.

Tuples are represented with JSON arrays, as documented in https://json-schema.org/understanding-json-schema/reference/array.html#tuple-validation.

A JSON schema for a tuple of 16 elements.

Tuples are represented with JSON arrays, as documented in https://json-schema.org/understanding-json-schema/reference/array.html#tuple-validation.