1 files changed, 95 insertions, 0 deletions
diff --git a/readme.rst b/readme.rst
new file mode 100644
index 0000000..adbc3ba
--- /dev/null
+++ b/readme.rst
@@ -0,0 +1,95 @@
+.. -*- mode: rst -*-
+.. -*-  coding: utf-8 -*-
+
+This is a sample project showing how to process http requests in a safe way in
+OCaml.
+
+For example:
+
+    - A service using the GET method cannot have any body resquest
+    - A service using the HEAD method cannot have any body response
+
+Interface
+=========
+
+The interface for a service is given in an OCaml module, and is declaring all
+the possibles values for a service.
+
+Each service shall describe:
+
+- an URL to the server
+- the body of the request
+- the body of the response
+
+.. code:: ocaml
+
+    type request = { value : string } [@@deriving yojson]
+
+    type response = { value : string; nbcar : int64 } [@@deriving yojson]
+
+    (** The method used in the service *)
+    let method_ = Services.POST
+
+    type placeholders = unit
+    (** No placeholder here in the request url *)
+
+    (** The path to the service, matching the type parameters *)
+    let path = Path.(T1 (Fixed (V_string.v "api/counter")))
+
+Here, we are not declaring any implementation, only the types.
+
+Implementation
+==============
+
+The server part
+---------------
+
+
+There is no implementation yet, this is done in the server, for example using
+`Dream_handler`:
+
+.. code:: ocaml
+
+    let handler =
+      Dream_handler.handle
+        (module Services_impl.Nb_car)
+        (fun (() : Services_impl.Nb_car.placeholders) body ->
+          Lwt.return_ok
+            Services_impl.Nb_car.
+              {
+                value = body.value;
+                nbcar = Int64.of_int (String.length body.value);
+              })
+
+As the url is also given in the service interface, we can also create the route:
+
+.. code:: ocaml
+
+    let route = Dream_handler.register (module Services_impl.Nb_car) handler
+
+    let () =
+      Dream.run @@ Dream.logger
+      @@ Dream.router
+           [
+             route;
+           ]
+
+
+The client part
+---------------
+
+This example use the library brr to make a request to this service:
+
+.. code:: ocaml
+
+    let futr = Js_handler.send (module Services_impl.Nb_car) () { value }
+
+Another example using cohttp :
+
+.. code:: ocaml
+
+  let root = "http://[::1]:8080"
+  let* result =
+    Cohttp_handler.request ~root
+      (module Services_impl.Nb_car)
+      () { value = "foobar" }