resto

A minimal OCaml library for type-safe HTTP/JSON RPCs
IN THIS PACKAGE
Module Resto
module Utils : sig ... end

Resto

Resto is a library for defining, serving, and querying a REST directory of RPC services.

Overview of Resto

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

Intended use of Resto

The intended use of Resto 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.
  • Use Resto_directory to register those services.

If you are writing a server, you can then:

  • Use 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:

  • Use Resto_cohttp_client.Client to make requests to these services.

And of course you can do both if you are writing both the server and the client.

type meth = [
| `GET
| `POST
| `DELETE
| `PUT
| `PATCH
]

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

val string_of_meth : [< meth ] -> string
val meth_of_string : string -> [> meth ] option
module MethMap : Map.S with type key = meth
module StringMap : Map.S with type key = string
type (_, _) eq =
| Eq : ( 'a, 'a ) eq

eq is an equality witness type. It is returned by some non-trivial equality-testing functions in the rest of this module. In general, it is intended to be used as follows:

match are_equal foo bar with | None -> (* values are not equal *) .. | Some Eq -> (* values are equal *) ..

module Arg : sig ... end

Arguments are documented serializers-deserializers for parameters.

module Path : sig ... end

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

module Description : sig ... end

Service directory description

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.

module type ENCODING = sig ... end

An ENCODING is a generic interface for modules that provide conversion from values to a different representation and back. This is used to abstract resto over specific representations of values.

module MakeService (Encoding : ENCODING) : sig ... end

Services.