EzRestoSourceEzResto is an abstraction layer on top of Resto that is simpler to use -- it is the *easy* Resto. We recommend that you read the documentation in this module as the basis for understanding EzResto and as a jumping point to understand Resto.
# Overview of EzResto
EzResto is a library for describing *services*. A service is the entry-point in an API: a URI/URL with some path parameters (some of the slash-separated segments are actually decoded as parameters), some additional query parameters (the part that looks like ?utm_parameter=from_email in the links of marketing emails) and other attributes depending on the method of the service.
For example, you can use EzResto to describe the directory of services that, as a whole, forms the API for a web-service. You can then use one of the other resto packages to implement a server that answers requests made to this API. Alternatively, you can use one of the other resto packages to make your program query such an API.
# Comparison with Resto
As stated earlier, EzResto is a light-weight version of Resto. Note that, whilst the interface is light-weight (i.e., the interfaces are simpler), the actual runtime cost is the same.
For example, in EzResto, paths (Path.t) have a single type parameter: this makes the most common use (adding suffixes to an existing path) simpler to reason about, but preclude the use of the prefix functionality of Resto (Resto.Path.prefix). But the runtime behavior (including computational and memory cost) is the same.
In general, you should use EzResto if it includes the features you need, and resort to Resto only on a by-need basis.
# Intended use of EzResto
The intended use of EzResto is as follows:
If you are writing a server, you can then:
EzResto_directory to register those services.Resto_cohttp_server.Server to spin up a server that answers requests to these services.Alternatively, if you are writing a client, you can then:
Resto_cohttp_client.Client to make requests to these services.The different methods that a service can be used by a service.
Query parameters are the key-value pairs that appear as ?key0=value0&key1=value1&.. at the end of the path in URIs/URLs.
The section below is to declare services.
type ('meth, 'params, 'query, 'input, 'output, 'error) service =
('meth, unit, 'params, 'query, 'input, 'output, 'error)
Resto.MakeService(Resto_json.Encoding).serviceThe type of services.
val get_service :
?description:string ->
query:'query Query.t ->
output:'output Json_encoding.encoding ->
error:'error Json_encoding.encoding ->
'params Path.t ->
([ `GET ], 'params, 'query, unit, 'output, 'error) serviceget_service ?description ~query ~output ~error path is a GET service that is intended to seat at the URI described by path and receive the additional parameters described by query. The values output and error describe the representations of the two possible returns for the service.
Note that, whilst get_service declares a service, the resulting service is not registered yet. This is handled in EzResto_directory.
post_service, delete_service, put_service, and patch_service are similar to get_service but for other methods.
Note that some of these functions take an additional input argument. This is only for the services with methods that expect additional parameters. It is used internally to encode/decode additional parameters passed in a dedicated payload rather than in the path/query parameters.
The following section is to manipulate requests.
These functions below are used to recover the components of a service.
This final section is for self-documentation: a service for service documentation.
type description_service =
([ `GET ],
unit * string list,
Description.request,
unit,
Json_schema.schema Description.directory,
unit)
service