REST method parameters annotated as Body will be used to build HTTP request body.
Base trait for annotations representing HTTP methods which may define a HTTP body.
Base trait for annotations representing HTTP methods which may define a HTTP body. This includes PUT, POST, PATCH and DELETE. Parameters of REST methods annotated with one of these tags are by default serialized into JSON (through encoding to JsonValue) and combined into JSON object that is sent as HTTP body.
Parameters may also contribute to URL path, HTTP headers and query parameters if annotated as Path, Header or Query.
trait SomeRestApi { @POST("users/create") def createUser(@Body user: User): Future[Unit] @PATCH("users/update") def updateUser(id: String, name: String): Future[User] } object SomeRestApi extends RestApiCompanion[SomeRestApi]
Base trait for tag annotations which specify how a HTTP body is built for invocation of particular method.
Requires that a method takes exactly one Body parameter which serializes directly into HttpBody.
See BodyMethodTag
Base class for companions of REST API traits used for both REST clients and servers.
Base class for companions of REST API traits used for both REST clients and servers.
Injects GenCodec
and GenKeyCodec
based serialization and forces derivation of
OpenApiMetadata
.
Base class for companions of REST API traits used only for REST clients to external services.
Base class for companions of REST API traits used only for REST clients to external services.
Injects GenCodec
and GenKeyCodec
based serialization.
Base class for companions of REST API traits used only for REST servers exposed to external world.
Base class for companions of REST API traits used only for REST servers exposed to external world.
Injects GenCodec
and GenKeyCodec
based serialization and forces derivation of
OpenApiMetadata
.
Causes the Body parameters of a HTTP REST method to be encoded as application/x-www-form-urlencoded
.
Causes the Body parameters of a HTTP REST method to be encoded as application/x-www-form-urlencoded
.
Each parameter value itself will be first serialized to QueryValue.
This annotation only applies to methods which may include HTTP body (i.e. not GET).
REST method annotated as @GET
will translate to HTTP GET request.
REST method annotated as @GET
will translate to HTTP GET request. By default, parameters of such method
are translated into URL query parameters (encoded as QueryValue). Alternatively, each parameter
may be annotated as Path or Header which means that it will be translated into HTTP header value
Defines GenCodec
and
GenKeyCodec
based serialization for REST API traits.
REST method parameters annotated as Header will be encoded as HeaderValue and added to HTTP headers.
REST method parameters annotated as Header will be encoded as HeaderValue and added to HTTP headers. Header name must be explicitly given as argument of this annotation.
Value used as encoding of Header parameters.
Value used to represent HTTP body.
Value used to represent HTTP body. Also used as direct encoding of Body parameters. Types that have
encoding to JsonValue automatically have encoding to HttpBody which uses application/json MIME type.
There is also a specialized encoding provided for Unit
which returns empty HTTP body when writing and ignores
the body when reading.
Enum representing HTTP methods.
Typeclass used during RestMetadata materialization to determine whether a real method is a valid HTTP method.
Typeclass used during RestMetadata materialization to determine whether a real method is a valid HTTP
method. Usually this means that the result must be a type wrapped into something that captures asynchronous
computation, e.g. Future
. Because REST framework core tries to be agnostic about this
asynchronous wrapper (not everyone likes Future
s), there are no default implicits provided for HttpResponseType.
They must be provided externally.
For example, FutureRestImplicits introduces an instance of HttpResponseType for Future[T]
,
for arbitrary type T
. For RestMetadata materialization this means that every method which returns a
Future
is considered a valid HTTP method. FutureRestImplicits is injected into materialization of
RestMetadata through one of the base companion classes, e.g. DefaultRestApiCompanion.
See MacroInstances for more information on injection of implicits.
Causes the Body parameters of a HTTP REST method to be encoded as application/json
.
Causes the Body parameters of a HTTP REST method to be encoded as application/json
.
Each parameter value itself will be first serialized to JsonValue.
This annotation only applies to methods which may include HTTP body (i.e. not GET)
and is assumed by default, so there should be no reason to apply it explicitly.
Value used as encoding of Body parameters of non-FormBody methods.
Indicates that a HTTP REST method takes no body.
See BodyMethodTag
See BodyMethodTag
See BodyMethodTag
REST method parameters annotated as Path will be encoded as PathValue and appended to URL path, in the declaration order.
Value used as encoding of Path parameters.
REST methods annotated as Prefix are expected to return another REST API trait as their result.
REST methods annotated as Prefix are expected to return another REST API trait as their result. They do not yet represent an actual HTTP request but contribute to URL path, HTTP headers and query parameters.
By default, parameters of a prefix method are interpreted as URL path fragments. Their values are encoded as PathValue and appended to URL path. Alternatively, each parameter may also be explicitly annotated as Header or Query.
NOTE: REST method is interpreted as prefix method by default which means that there is no need to apply Prefix annotation explicitly unless you want to specify a custom path.
REST method parameters annotated as Query will be encoded as QueryValue and added to URL query parameters.
REST method parameters annotated as Query will be encoded as QueryValue and added to URL query parameters. Parameters of GET REST methods are interpreted as Query parameters by default.
Value used as encoding of Query parameters and Body parameters of FormBody methods.
Base class for REST trait companions.
Base class for REST trait companions. Reduces boilerplate needed in order to define appropriate instances
of AsRawReal
and RestMetadata
for given trait. The Implicits
type parameter lets you inject additional implicits
into macro materialization of these instances, e.g. DefaultRestImplicits.
Usually, for even less boilerplate, this base class is extended by yet another abstract class which fixes
the Implicits
type, e.g. DefaultRestApiCompanion.
Base class for companion objects of ADTs (case classes, objects, sealed hierarchies) which are used as parameter or result types in REST API traits.
Base class for companion objects of ADTs (case classes, objects, sealed hierarchies) which are used as
parameter or result types in REST API traits. Automatically provides instances of GenCodec
and RestSchema
.
case class User(id: String, name: String, birthYear: Int) object User extends RestDataCompanion[User]
Base trait for tag annotations that determine how a REST method is translated into actual HTTP request.
Base trait for tag annotations that determine how a REST method is translated into actual HTTP request.
A REST method may be annotated with one of HTTP method tags (GET, PUT, POST, PATCH, DELETE)
which means that this method represents actual HTTP call and is expected to return a Future[Result]
where
Result
is encodable as RestResponse.
If a REST method is not annotated with any of HTTP method tags, Prefix is assumed by default which means that this method only contributes to URL path, HTTP headers and query parameters but does not yet represent an actual HTTP request. Instead, it is expected to return some other REST API trait.
REST method parameters annotated as Body will be used to build HTTP request body. How exactly that happens depends on BodyTypeTag applied on a method. By default, JsonBody is assumed which means that body parameters will be combined into a single JSON object sent as body. Body parameters are allowed only in REST methods annotated as POST, PATCH, PUT or DELETE.
Body annotation is assumed by default for parameters of all methods which may include HTTP body. This means that there's usually no reason to apply this annotation explicitly. It may only be useful when wanting to customize JSON/form field name.