REST methods that can send HTTP body (POST, PATCH, PUT and DELETE) may take a single parameter annotated as Body which will be encoded as HttpBody and sent as the body of HTTP request.
REST method parameters annotated as BodyField will be encoded as either JsonValue and combined into a JSON object that will be sent as HTTP body.
REST method parameters annotated as BodyField will be encoded as either JsonValue and combined into a JSON object that will be sent as HTTP body. Body parameters are allowed only in REST methods annotated as POST, PATCH, PUT or DELETE. Actually, parameters of these methods are interpreted as BodyField by default which means that this annotation rarely needs to be applied explicitly.
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.
REST method may also take a single parameter representing the entire HTTP body. Such parameter must be annotated as Body and must be the only body parameter of that method. Value of this parameter will be encoded as HttpBody which doesn't necessarily have to be JSON (it may define its own MIME type).
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]
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 Future
as the wrapper for asynchronous responses and GenCodec
/GenKeyCodec
based serialization
for parameters and responses.
Also, 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 Future
as the wrapper for asynchronous responses and GenCodec
/GenKeyCodec
based serialization
for parameters and responses.
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 Future
as the wrapper for asynchronous responses and GenCodec
/GenKeyCodec
based serialization
for parameters and responses.
Also, 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 include HTTP body (i.e. not GET
) and it must not be
a method with a single body parameter (Body). Methods with single body parameter can send their body
as application/x-www-form-urlencoded
by defining custom serialization of its parameter into HttpBody.
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.
Base class for RestMethodTags representing actual HTTP methods, as opposed to Prefix methods.
See BodyMethodTag
See BodyMethodTag.
See BodyMethodTag. This is the default tag for untagged methods which are not recognized as Prefix methods (i.e. their result type is not another REST trait).
See BodyMethodTag
REST method parameters annotated as Path will be encoded as PathValue and appended to URL path, in the declaration order.
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.
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 AsyncWrapper[Result]
where
Result
is encodable as RestResponse and AsyncWrapper
represents some abstraction over asynchronous
computations (Future
by default - see DefaultRestApiCompanion).
If a REST method is not annotated with any of HTTP method tags, then either POST is assumed (if result type is a valid result type for HTTP method) or Prefix is assumed (if result type is another REST trait). Prefix 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 instance of some other REST API trait which will ultimately determine the actual HTTP call.
REST methods that can send HTTP body (POST, PATCH, PUT and DELETE) may take a single parameter annotated as Body which will be encoded as HttpBody and sent as the body of HTTP request. Such a method may not define any other body parameters (although it may take additional Path, Header or Query parameters).
The single body parameter may have a completely custom encoding to HttpBody which may define its own MIME type and doesn't necessarily have to be JSON.