ezresto 0.5 · OCaml Package

EzResto 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 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. 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:

Define arguments, paths, query fields, and queries as required by the API you describe.
Define services using the previously defined arguments, paths, query fields and queries.

If you are writing a server, you can then:

Use EzResto_directory to register those services.
Use Resto_cohttp_server to spin up a server that answers requests to these services.

Alternatively, if you are writing a client, you can then:

Use Resto_cohttp_client to make requests to these services.

type meth = [

| `GET
| `POST
| `DELETE
| `PUT
| `PATCH

]

The different methods that a service can be used by a service.

module Arg : sig ... end

Arguments are documented serializers-deserializers for parameters.

module Path : sig ... end

Paths describe URIs/URLs: segments separated by slashes (/).

module Query : sig ... end

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).service

The 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) service

get_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.

val post_service : 
  ?description:string ->
  query:'query Query.t ->
  input:'input Json_encoding.encoding ->
  output:'output Json_encoding.encoding ->
  error:'error Json_encoding.encoding ->
  'params Path.t ->
  ([ `POST ], 'params, 'query, 'input, 'output, 'error) service

val delete_service : 
  ?description:string ->
  query:'query Query.t ->
  output:'output Json_encoding.encoding ->
  error:'error Json_encoding.encoding ->
  'params Path.t ->
  ([ `DELETE ], 'params, 'query, unit, 'output, 'error) service

val put_service : 
  ?description:string ->
  query:'query Query.t ->
  input:'input Json_encoding.encoding ->
  output:'output Json_encoding.encoding ->
  error:'error Json_encoding.encoding ->
  'params Path.t ->
  ([ `PUT ], 'params, 'query, 'input, 'output, 'error) service

val patch_service : 
  ?description:string ->
  query:'query Query.t ->
  input:'input Json_encoding.encoding ->
  output:'output Json_encoding.encoding ->
  error:'error Json_encoding.encoding ->
  'params Path.t ->
  ([ `PATCH ], 'params, 'query, 'input, 'output, 'error) service

The following section is to manipulate requests.

type 'input input =

| No_input : unit input
| Input : 'input Json_encoding.encoding -> 'input input

type 'input request = {

meth : meth;
uri : Uri.t;
input : 'input input;

}

val forge_request : 
  ('meth, 'params, 'query, 'input, 'output, 'error) service ->
  ?base:Uri.t ->
  'params ->
  'query ->
  'input request

These functions below are used to recover the components of a service.

val query : 
  ('meth, 'params, 'query, 'input, 'output, 'error) service ->
  'query Query.t

val input_encoding : 
  ('meth, 'params, 'query, 'input, 'output, 'error) service ->
  'input input

val output_encoding : 
  ('meth, 'params, 'query, 'input, 'output, 'error) service ->
  'output Json_encoding.encoding

val error_encoding : 
  ('meth, 'params, 'query, 'input, 'output, 'error) service ->
  'error Json_encoding.encoding

This final section is for self-documentation: a service for service documentation.

module Description = Resto.Description

type description_service =
  ([ `GET ],
    unit * string list,
    Description.request,
    unit,
    Json_schema.schema Description.directory,
    unit)
    service

val description_service : 
  ?description:string ->
  unit Path.path ->
  description_service

package ezresto