package ez_api

  1. Overview
  2. Docs

Description

Published: 09 Jul 2024

README

README.md

ez_api : a simple library to write client/server web APIs

EzAPI is a collection of libraries and tools to handle APIs that can be installed with opam:

opam install ez_api

The main package ez_api accessible via the module EzAPI defines services handling encoding (via json-data-encoding), errors, securites, and documentation.

Around this ez_api provides a multitude of sub-package, sometimes depending on optional libraries.

Encoding

ez_api proposes a small addition to json-data-encoding for easier coding (ez_api.encoding) and to avoid overflow when using js_of_ocaml (ez_api.encoding_js).

Client

ez_api implements client side requests for unix and web using different libraries. The main sub-package ez_api.req (or ez_api.req_lwt if you're using lwt) is a virtual implemetation that needs to be complemented with a implementation of your choice:

For unix:

  • curl implementation ez_api.icurl or ez_api.icurl_lwt that requires curl library:

opam depext ocurl
opam install ocurl
  • cohttp implementation ez_api.icohttp or ez_api.icohttp_lwt that requires tls and cohttp-lwt-unix libraries:

opam depext tls
opam install tls cohttp-lwt-unix

For web:

  • javascript XHR implemenation ez_api.ixhr or ez_api.ixhr_lwt

  • cohttp web ez_api.icoxhr or ez_api.icoxhr_lwt that requires cohttp-lwt-jsoo:

opam install cohttp-lwt-jsoo
  • fetch implemetation ez_api.ifetch or ez_api.ifetch_lwt requiring ezjs_fetch

opam install ezjs_fetch

All these implementation can also be used directly by removing the i preceding the sub-package name.

Websocket Client

As for the traditional client, ez_api provides a virtual implementation of a websocket client: ez_api.ws It can be complemented with:

  • For unix the implementation ez_api.ws_cohttp requires cohttp-lwt-unix and websocket-lwt-unix:

opam install cohttp-lwt-unix websocket-lwt-unix
  • For javascript ez_api.ws_js that uses the native implementation of the browsers

Server

The server part (ez_api.server) requires more optional unix dependencies from geoip:

opam depext geoip
opam install calendar geoip

As for the client, the server has a virtual implementation (ez_api.server) that can be complemented with either cohttp or httpaf:

  • for cohttp (ez_api.iserver_cohttp), you will need cohttp-lwt-unix:

opam install cohttp-lwt-unix
  • for httpaf (ez_api.iserver_httpaf), you will need httpaf-lwt-unix:

opam install httpaf-lwt-unix

These implementation can also be used directly by removing the i preceding the sub-package name.

If you need your server to handle websocket, you will need to install the corresponding dependencies:

  • for cohttp server:

opam install websocket-lwt-unix
  • for httpaf server:

opam pin add websocket-httpaf.~dev git+https://github.com/anmonteiro/websocket-httpaf.git
opam pin add websocket-httpaf-lwt.~dev git+https://github.com/anmonteiro/websocket-httpaf.git

More Tools

ez_api provides useful tools for server and client:

  • server side sessions with different kind of authentication. (ez_api.session, ez_api.session_client, ez_api.server_session)

  • recaptcha verification (ez_api.recaptcha)

  • sending email via sendgrid (ez_api.sendgrid)

  • exporting the documentation of your API to openapi-specs JSON (ez_api.openAPI)

  • ppx rewriter (ez_api.ppx) to simplify some server/handler registration

Documentation

The documentation for the different libraries can be found here: API Reference

Usage

Have a look at the files in test

Dependencies (6)

  1. uuidm
  2. ezjsonm >= "1.1.0"
  3. lwt >= "4.0.0"
  4. json-data-encoding >= "1.0.1"
  5. ocaml >= "4.08"
  6. dune >= "2.8"

Dev Dependencies

None

Used by (2)

  1. jext
  2. ozulip

Conflicts (12)

  1. tls >= "1.0.0"
  2. result < "1.5"
  3. ppx_deriving_encoding != "0.3.0"
  4. ppxlib < "0.18.0"
  5. digestif < "1.0.0"
  6. ocurl < "0.8.0"
  7. ezjs_fetch < "0.2"
  8. httpaf-lwt-unix < "0.6.0"
  9. cohttp-lwt-jsoo < "5.0.0"
  10. cohttp-lwt-unix < "5.0.0"
  11. js_of_ocaml-lwt < "4.0.0"
  12. calendar < "2.03"
OCaml

Innovation. Community. Security.