Documentation on the http-based Worker Replication service

doc/dev/api/index.rst

@@ -0,0 +1,16 @@
+.. note::
+
+   Information in this guide corresponds to the version **40** of the Qserv REST API. Keep in mind
+   that each implementation of the API has a specific version. The version number will change
+   if any changes to the implementation or the API that might affect users will be made.
+   The current document will be kept updated to reflect the latest version of the API.
+
+##############################
+The internal REST API of Qserv
+##############################
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   repl-worker

doc/dev/api/introduction.rst

@@ -0,0 +1,25 @@
+.. _qserv-api-introduction:
+
+Introduction
+============
+
+This document presents a collection of the internal REST APIs that exist in the Qserv implementation.
+Qserv developers may use these APIs to interact with various components of Qserv.
+
+The Qserv REST API is a collection of RESTful web services that provide access to various components of the Qserv system.
+The API enforeces a specific interaction model between the client and the server. The following hihglites are worth mentioning:
+
+- All ``POST``, ``PUT`` and ``DELETE`` requests must be accompanied by a JSON payload.
+- Responses of all but a few select services are in JSON format.Exceptions are documented in the API documentation.
+- Schemas of the JSON requests and payloads are defined in the API documentation.
+- The API is versioned. The version number is included in the URL path of the ``GET`` requests, and it's
+  inluded into the JSON payload of the ``POST``, ``PUT`` and ``DELETE`` requests.
+- All API services are protected by an authentication mechanism. The client must provide a valid
+  authentication token in the JSON payload of the the ``POST``, ``PUT`` and ``DELETE`` requests.
+  No authentication is required for the ``GET`` requests.
+
+The general information on the structure of the API can be found in the following document:
+
+- :ref:`ingest-general`
+
+The rest of the current document provides detailed information on the individual services that are available in the Qserv API.