Add documentation about API

docs/API.rst

@@ -3,3 +3,56 @@
 ===
 API
 ===
+
+Mockservr exposes an HTTP API which allow to get information about current endpoints, and to update them if needed.
+This API is available through HTTP queries on `http://localhost:4580` (the API is exposed through the port 4580 of
+the Mockservr's container).
+
+-------------
+API Endpoints
+-------------
+
+All endpoints are JSON endpoints (`Content-Type: application/json`) and must be prefixed with `/api`.
+
+`/api` endpoint
+===============
+
+`GET` method
+~~~~~~~~~~~~
+
+The response is an object with a single attribute `httpEndpoints`, it contains the number of endpoints currently served
+by Mockservr.
+
+`/api/http-endpoints` endpoint
+==============================
+
+`GET` Method
+~~~~~~~~~~~~
+
+The response is a collection of all HTTP endpoints cuurrently served by Mockservr. The response includes the internal
+ID of the endpoint and the source (mock file or API).
+
+`POST` method
+~~~~~~~~~~~~~
+
+It expects a JSON body as defined in :ref:`http_mocking`, defining an endpoint with a Request and a Response.
+
+The response contains the newly created endpoint with its ID and source. If any error occurred, the response is an
+HTTP 400 response with a json object that contains all encountered errors.
+
+`/api/http-endpoints/:id` endpoint
+==================================
+
+`GET` Method
+~~~~~~~~~~~~
+
+The response is an object defining the endpoint corresponding to the given `:id`.
+
+`DELETE` method
+~~~~~~~~~~~~~
+
+Deletes the endpoint from Mockservr. The response is an HTTP 204 response. If any error occurred, the response is an
+HTTP 400 response with a json object that contains all encountered errors.
+
+.. note::
+    `DELETE` method does not delete the mock file, if the target endpoint is defined in a mock file.

docs/http_mocking.rst

@@ -1,3 +1,5 @@
+.. _http_mocking:
+
 ============
 HTTP Mocking
 ============
@@ -215,6 +217,9 @@ which the `callCount` lies.
 
 In the above example, the API has a rate limit of 2 calls every 5 seconds.
 
+.. note::
+    It is possible to add a custom Response in the `html.rateLimit` object.
+
 .. _Request:
 
 *******
@@ -1072,6 +1077,9 @@ __ ApacheVelocityDoc_
         - an `endpoint` which is the object representing the matched endpoint from the mock definition file
         - a `context` which is the optional `velocity.context` object defined above
 
+    The `endpoint` object contains the parameters that were matched against the incoming HTTP request. It also contains
+    information about how the parameter was matched (e.g: boolean or regex's capturing group).
+
 `weight` option
 ---------------