Endpoint
A description of an endpoint with the given inputs & outputs. The inputs are divided into two parts: security (A
) and regular inputs
(I
). There are also two kinds of outputs: error outputs (E
) and regular outputs (O
).
In case there are no security inputs, the PublicEndpoint alias can be used, which omits the A
parameter type.
An endpoint can be interpreted as a server, client or documentation. The endpoint requires that server/client interpreters meet the
capabilities specified by R
(if any).
When interpreting an endpoint as a server, the inputs are decoded and the security logic is run first, before decoding the body in the regular inputs. This allows short-circuiting further processing in case security checks fail. Server logic can be provided using EndpointServerLogicOps.serverSecurityLogic variants for secure endpoints, and EndpointServerLogicOps.serverLogic variants for public endpoints.
A concise description of an endpoint can be generated using the EndpointMetaOps.show method.
- Type Params
- A
Security input parameter types.
- E
Error output parameter types.
- I
Input parameter types.
- O
Output parameter types.
- R
The capabilities that are required by this endpoint's inputs/outputs. This might be
Any
(no requirements), sttp.capabilities.Effect (the interpreter must support the given effect type), sttp.capabilities.Streams (the ability to send and receive streaming bodies) or sttp.capabilities.WebSockets (the ability to handle websocket requests).
Type members
Types
Value members
Concrete methods
Inherited methods
Adds a new error variant, where the current error output is represented as a Left
, and the given one as a Right
.
Adds a new error variant, where the current error output is represented as a Left
, and the given one as a Right
.
- Inherited from
- EndpointErrorOutputVariantsOps
Adds a new error output variant. The new variant will be checked first during encoding/decoding, before the endpoint's current output.
Adds a new error output variant. The new variant will be checked first during encoding/decoding, before the endpoint's current output.
More specifically, the current error output is replaced with a Tapir.oneOf output, where:
- the first output variant is the given
o
- the second output variant is the current
errorOutput
, wrapped with Tapir.oneOfDefaultVariant
- Type Params
- E2
A common supertype of the new variant and the current output
E
.
- Value Params
- o
The variant to add. Can be created given an output with one of the Tapir.oneOfVariant methods.
- Inherited from
- EndpointErrorOutputVariantsOps
Adds a new error variant, where the current error output is mapped to conform to the common supertype E2
using the f
and g
functions.
Adds a new error variant, where the current error output is mapped to conform to the common supertype E2
using the f
and g
functions.
- Inherited from
- EndpointErrorOutputVariantsOps
Adds new error output variants. The new variants will be checked first during encoding/decoding, before the endpoint's current output.
Adds new error output variants. The new variants will be checked first during encoding/decoding, before the endpoint's current output.
More specifically, the current error output is replaced with a Tapir.oneOf output, where:
- the initial output variants are the given
first
andother
- the last output variant is the current
errorOutput
, wrapped with Tapir.oneOfDefaultVariant
- Type Params
- E2
A common supertype of the new variant and the current output
E
.
- Value Params
- first
The first variant to add. Can be created given an output with one of the Tapir.oneOfVariant methods.
- other
Additional variants to add.
- Inherited from
- EndpointErrorOutputVariantsOps
Adds new error variants, where the current error output is mapped to conform to the common supertype E2
using the f
and g
functions.
Adds new error variants, where the current error output is mapped to conform to the common supertype E2
using the f
and g
functions.
- Inherited from
- EndpointErrorOutputVariantsOps
- Inherited from
- EndpointInputsOps
- Inherited from
- EndpointErrorOutputsMacros
- Inherited from
- EndpointSecurityInputsMacros
- Inherited from
- EndpointOutputsOps
- Inherited from
- EndpointOutputsOps
- Inherited from
- EndpointErrorOutputsOps
- Inherited from
- EndpointInputsOps
- Inherited from
- EndpointOutputsOps
- Inherited from
- EndpointOutputsOps
- Inherited from
- EndpointSecurityInputsOps
Renders endpoint path, by default all parametrised path and query components are replaced by {param_name} or {paramN}, e.g. for
Renders endpoint path, by default all parametrised path and query components are replaced by {param_name} or {paramN}, e.g. for
endpoint.in("p1" / path[String] / query[String]("par2"))
returns /p1/{param1}?par2={par2}
- Value Params
- includeAuth
Should authentication inputs be included in the result.
- Inherited from
- EndpointMetaOps
- Inherited from
- EndpointSecurityInputsOps
Combine this public endpoint description with a function, which implements the server-side logic. The logic returns a result, which is
either an error or a successful output, wrapped in an effect type F
. For secure endpoints, use serverSecurityLogic.
Combine this public endpoint description with a function, which implements the server-side logic. The logic returns a result, which is
either an error or a successful output, wrapped in an effect type F
. For secure endpoints, use serverSecurityLogic.
A server endpoint can be passed to a server interpreter. Each server interpreter supports effects of a specific type(s).
Both the endpoint and logic function are considered complete, and cannot be later extended through the returned ServerEndpoint value (except for endpoint meta-data). Secure endpoints allow providing the security logic before all the inputs and outputs are specified.
- Inherited from
- EndpointServerLogicOps
Like serverLogic, but specialised to the case when the result is always an error (Left
), hence when the logic type can be
simplified to I => F[E]
.
Like serverLogic, but specialised to the case when the result is always an error (Left
), hence when the logic type can be
simplified to I => F[E]
.
- Inherited from
- EndpointServerLogicOps
Like serverLogic, but specialised to the case when the logic function is pure, that is doesn't have any side effects.
Like serverLogic, but specialised to the case when the logic function is pure, that is doesn't have any side effects.
- Inherited from
- EndpointServerLogicOps
Same as serverLogic, but requires E
to be a throwable, and coverts failed effects of type E
to endpoint errors.
Same as serverLogic, but requires E
to be a throwable, and coverts failed effects of type E
to endpoint errors.
- Inherited from
- EndpointServerLogicOps
Like serverLogic, but specialised to the case when the result is always a success (Right
), hence when the logic type can be
simplified to I => F[O]
.
Like serverLogic, but specialised to the case when the result is always a success (Right
), hence when the logic type can be
simplified to I => F[O]
.
- Inherited from
- EndpointServerLogicOps
Combine this endpoint description with a function, which implements the security logic of the endpoint.
Combine this endpoint description with a function, which implements the security logic of the endpoint.
Subsequently, the endpoint inputs and outputs can be extended (for error outputs, new variants can be added, but they cannot be arbitrarily extended). Then the main server logic can be provided, given a function which accepts as arguments the result of the security logic and the remaining input. The final result is then a ServerEndpoint.
A complete server endpoint can be passed to a server interpreter. Each server interpreter supports effects of a specific type(s).
An example use-case is defining an endpoint with fully-defined errors, and with security logic built-in. Such an endpoint can be then extended by multiple other endpoints, by specifying different inputs, outputs and the main logic.
- Inherited from
- EndpointServerLogicOps
Like serverSecurityLogic, but specialised to the case when the result is always an error (Left
), hence when the logic type can
be simplified to A => F[E]
.
Like serverSecurityLogic, but specialised to the case when the result is always an error (Left
), hence when the logic type can
be simplified to A => F[E]
.
- Inherited from
- EndpointServerLogicOps
Like serverSecurityLogic, but specialised to the case when the logic function is pure, that is doesn't have any side effects.
Like serverSecurityLogic, but specialised to the case when the logic function is pure, that is doesn't have any side effects.
- Inherited from
- EndpointServerLogicOps
Same as serverSecurityLogic, but requires E
to be a throwable, and coverts failed effects of type E
to endpoint errors.
Same as serverSecurityLogic, but requires E
to be a throwable, and coverts failed effects of type E
to endpoint errors.
- Inherited from
- EndpointServerLogicOps
Like serverSecurityLogic, but specialised to the case when the result is always a success (Right
), hence when the logic type can
be simplified to A => F[U]
.
Like serverSecurityLogic, but specialised to the case when the result is always a success (Right
), hence when the logic type can
be simplified to A => F[U]
.
- Inherited from
- EndpointServerLogicOps
Basic information about the endpoint, excluding mapping information, with inputs sorted (first the method, then path, etc.)
Basic information about the endpoint, excluding mapping information, with inputs sorted (first the method, then path, etc.)
- Inherited from
- EndpointMetaOps
Detailed description of the endpoint, with inputs/outputs represented in the same order as originally defined, including mapping information.
Detailed description of the endpoint, with inputs/outputs represented in the same order as originally defined, including mapping information.
- Inherited from
- EndpointMetaOps
Equivalent to .toString
, shows the whole case class structure.
Equivalent to .toString
, shows the whole case class structure.
- Inherited from
- EndpointMetaOps