Packages

package algebra

Algebra interfaces

Source
package.scala
Linear Supertypes
Content Hierarchy
Ordering
  1. Grouped
  2. Alphabetic
  3. By Inheritance
Inherited
  1. algebra
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Package Members

  1. package circe
  2. package playjson

Type Members

  1. trait Assets extends EndpointsWithCustomErrors

    Describes endpoints related to static assets (e.g.

    Describes endpoints related to static assets (e.g. medias, scripts, stylesheets, etc.)

  2. trait BasicAuthentication extends EndpointsWithCustomErrors

    Provides vocabulary to describe endpoints that use Basic HTTP authentication.

    Provides vocabulary to describe endpoints that use Basic HTTP authentication.

    This trait works fine, but developers are likely to implement their own authentication mechanism, specific to their application.

  3. trait BuiltInErrors extends Errors

    Interpreter for the Errors algebra that uses endpoints4s built-in error types:

    Interpreter for the Errors algebra that uses endpoints4s built-in error types:

    • Invalid for client errors,
    • and Throwable for server error.

    Both types of errors are serialized into a JSON array containing string error values.

  4. trait ChunkedEntities extends EndpointsWithCustomErrors

    Algebra interface for describing request and response entities that use the chunked transfer-encoding.

    Algebra interface for describing request and response entities that use the chunked transfer-encoding.

    It introduces a type Chunks[A], which models a stream of chunks of type A. It also introduces constructors for chunked request and response entities.

    Example:

    val notifications: Endpoint[Unit, Chunks[String]] =
      endpoint(
        get(path / "notifications"),
        ok(textChunksResponse)
      )

    Or also:

    val upload: Endpoint[Chunks[Array[Byte]], Unit] =
      endpoint(
        post(path / "upload", bytesChunksRequest),
        ok(emptyResponse)
      )
  5. trait ChunkedJsonEntities extends ChunkedEntities with JsonCodecs

    Enriches the ChunkedEntities algebra with constructors of request and response entities carrying JSON documents.

    Enriches the ChunkedEntities algebra with constructors of request and response entities carrying JSON documents.

    Example:

    val events =
      endpoint(
        get(path / "events"),
        ok(jsonChunksResponse[Event])
      )
  6. type Documentation = Option[String]
  7. trait Endpoints extends EndpointsWithCustomErrors with BuiltInErrors

    Algebra interface for describing endpoints made of requests and responses.

    Algebra interface for describing endpoints made of requests and responses.

    Requests and responses contain headers and entity.

    /**
      * Describes an HTTP endpoint whose:
      *  - request uses verb “GET”,
      *  - URL is made of path “/foo”,
      *  - response has no entity
      */
    val example = endpoint(get(path / "foo"), emptyResponse)

    This trait uses BuiltInErrors to model client and server errors.

  8. trait EndpointsWithCustomErrors extends Requests with Responses with Errors

    Algebra interface for describing endpoints made of requests and responses.

  9. trait Errors extends AnyRef

    Defines the error types used to model client and server errors.

    Defines the error types used to model client and server errors.

    The ClientErrors type is used by endpoints4s to model errors coming from the client (missing query parameter, invalid entity, etc.).

    The ServerError type is used by endpoints4s to model errors coming from the server business logic.

    The badRequest and internalServerError operations defined in Responses define responses carrying entities of type ClientErrors and ServerError, respectively.

    Interpreters are expected to use the clientErrorsResponse and serverErrorResponse operations defined here to handle client and server errors, respectively.

    See also

    BuiltInErrors

  10. final class ExternalDocumentationObject extends Serializable

  11. trait JsonCodecs extends JsonEntities

    Fixes both the JsonRequest and JsonResponse types to be a same JsonCodec type.

    Fixes both the JsonRequest and JsonResponse types to be a same JsonCodec type.

    This trait is used as an implementation detail (to reuse code between JsonEntitiesFromSchemas and JsonEntitiesFromCodecs) and is not useful to end-users.

  12. trait JsonEntities extends EndpointsWithCustomErrors

    Algebra interface for describing JSON entities in requests and responses.

    Algebra interface for describing JSON entities in requests and responses.

    Generally, this algebra is not directly used, but one of its specialized algebras is used instead: JsonEntitiesFromSchemas or JsonEntitiesFromCodecs.

    /**
      * Describes an HTTP endpoint whose:
      *  - request uses verb “GET”,
      *  - URL is made of the segment “/user” followed by a `String` segment,
      *  - response content type is JSON and contains a `User`
      */
    val example = endpoint(get(path / "user" / segment[UUID]), jsonResponse[User])
  13. trait JsonEntitiesFromCodecs extends JsonCodecs

    Turns a JsonCodec into a Codec.

  14. trait JsonEntitiesFromSchemas extends JsonCodecs with JsonSchemas

    Partially applies the JsonEntities algebra interface to fix the JsonRequest and JsonResponse types to be JsonSchema.

  15. trait JsonSchemas extends TuplesSchemas with PartialInvariantFunctorSyntax

    An algebra interface for describing algebraic data types.

    An algebra interface for describing algebraic data types. Such descriptions can be interpreted to produce a JSON schema of the data type, a JSON encoder, a JSON decoder, etc.

    A description contains the fields of a case class and their type, and the constructor names of a sealed trait.

    For instance, consider the following record type:

    case class User(name: String, age: Int)

    Its description is the following:

    object User {
      implicit val schema: JsonSchema[User] = (
        field[String]("name") zip
        field[Int]("age")
      ).xmap((User.apply _).tupled)(Function.unlift(User.unapply))
    }

    The description says that the record type has two fields, the first one has type String and is named “name”, and the second one has type Int and name “age”.

    To describe sum types you have to explicitly “tag” each alternative:

    sealed trait Shape
    case class Circle(radius: Double) extends Shape
    case class Rectangle(width: Double, height: Double) extends Shape
    
    object Shape {
      implicit val schema: JsonSchema[Shape] = {
        val circleSchema = field[Double]("radius").xmap(Circle)(Function.unlift(Circle.unapply))
        val rectangleSchema = (
          field[Double]("width") zip
          field[Double]("height")
        ).xmap((Rectangle.apply _).tupled)(Function.unlift(Rectangle.unapply))
        (circleSchema.tagged("Circle") orElse rectangleSchema.tagged("Rectangle"))
          .xmap[Shape] {
            case Left(circle) => circle
            case Right(rect)  => rect
          } {
            case c: Circle    => Left(c)
            case r: Rectangle => Right(r)
          }
      }
    }
  16. trait LowLevelEndpoints extends EndpointsWithCustomErrors

    Provides a way to define endpoints that directly expose the low level APIs of the interpreters.

    Provides a way to define endpoints that directly expose the low level APIs of the interpreters.

    Using this trait is not recommended because endpoints defined using these methods miss the opportunity to share a consistent protocol between client and server interpreters. However, it can be useful for transitioning legacy code.

    Example of endpoint definition:

    val someEndpoint = endpoint(post(path, rawRequestEntity), rawResponseEntity)

    Endpoint implementation:

    someEndpoint.implementedBy { request =>
      Ok(request.body.asText.getOrElse("Unable to decode request entity"))
    }

    XMLHttpRequest call:

    someEndpoint(xhr => "Foo")
      .map(response => println(response.responseText))
  17. trait Methods extends AnyRef

  18. trait MuxEndpoints extends EndpointsWithCustomErrors

    Algebra interface for describing endpoints such that one endpoint can handle several types of requests and responses.

  19. trait MuxRequest extends AnyRef

    Multiplexed request type

  20. trait NoDocsJsonSchemas extends JsonSchemas

    Helper trait that can be mixed into JsonSchemas to implement (as no-ops) the documentation related methods.

    Helper trait that can be mixed into JsonSchemas to implement (as no-ops) the documentation related methods. This is useful for implementing any non-documentation inteprereters.

  21. trait Requests extends Urls with Methods with SemigroupalSyntax

  22. trait Responses extends StatusCodes with InvariantFunctorSyntax

  23. trait StatusCodes extends AnyRef

  24. final class Tag extends Serializable

  25. trait TuplesSchemas extends AnyRef

    Generated trait that provides JsonSchema constructors for tuples from 2 to 22 elements.

  26. trait Urls extends PartialInvariantFunctorSyntax

    Algebra interface for describing URLs made of a path and a query string.

    Algebra interface for describing URLs made of a path and a query string.

    A path is itself made of segments chained together.

    A query string is made of named parameters.

    /**
      * Describes an URL starting with a segment containing “articles”, followed
      * by another `String` segment, and a query string containing
      * a mandatory `Lang` parameter named “lang”, and an
      * optional `Int` parameter named “page”.
      *
      * Examples of matching URLs:
      *
      * - /articles/kitchen?lang=fr
      * - /articles/garden?lang=en&page=2
      */
    val example = path / "articles" / segment[String]() /? (qs[Lang]("lang") & qs[Option[Int]]("page"))

Value Members

  1. object BasicAuthentication
  2. object ExternalDocumentationObject extends Serializable
  3. object Tag extends Serializable

Inherited from AnyRef

Inherited from Any

Algebras

Interpreters

Ungrouped