doc: Split references out into smaller files

Closes #1852

doc/REST_backend.rst

@@ -0,0 +1,145 @@
+************
+REST Backend
+************
+
+Restic can interact with HTTP Backend that respects the following REST
+API.
+
+The following values are valid for ``{type}``:
+
+ * ``data``
+ * ``keys``
+ * ``locks``
+ * ``snapshots``
+ * ``index``
+ * ``config``
+
+The API version is selected via the ``Accept`` HTTP header in the request. The
+following values are defined:
+
+ * ``application/vnd.x.restic.rest.v1`` or empty: Select API version 1
+ * ``application/vnd.x.restic.rest.v2``: Select API version 2
+
+The server will respond with the value of the highest version it supports in
+the ``Content-Type`` HTTP response header for the HTTP requests which should
+return JSON. Any different value for this header means API version 1.
+
+The placeholder ``{path}`` in this document is a path to the repository, so
+that multiple different repositories can be accessed. The default path is
+``/``. The path must end with a slash.
+
+POST {path}?create=true
+=======================
+
+This request is used to initially create a new repository. The server
+responds with "200 OK" if the repository structure was created
+successfully or already exists, otherwise an error is returned.
+
+DELETE {path}
+=============
+
+Deletes the repository on the server side. The server responds with "200
+OK" if the repository was successfully removed. If this function is not
+implemented the server returns "501 Not Implemented", if this it is
+denied by the server it returns "403 Forbidden".
+
+HEAD {path}/config
+==================
+
+Returns "200 OK" if the repository has a configuration, an HTTP error
+otherwise.
+
+GET {path}/config
+=================
+
+Returns the content of the configuration file if the repository has a
+configuration, an HTTP error otherwise.
+
+Response format: binary/octet-stream
+
+POST {path}/config
+==================
+
+Returns "200 OK" if the configuration of the request body has been
+saved, an HTTP error otherwise.
+
+GET {path}/{type}/
+==================
+
+API version 1
+-------------
+
+Returns a JSON array containing the names of all the blobs stored for a given
+type, example:
+
+.. code:: json
+
+    [
+      "245bc4c430d393f74fbe7b13325e30dbde9fb0745e50caad57c446c93d20096b",
+      "85b420239efa1132c41cea0065452a40ebc20c6f8e0b132a5b2f5848360973ec",
+      "8e2006bb5931a520f3c7009fe278d1ebb87eb72c3ff92a50c30e90f1b8cf3e60",
+      "e75c8c407ea31ba399ab4109f28dd18c4c68303d8d86cc275432820c42ce3649"
+    ]
+
+API version 2
+-------------
+
+Returns a JSON array containing an object for each file of the given type. The
+objects have two keys: ``name`` for the file name, and ``size`` for the size in
+bytes.
+
+.. code:: json
+
+    [
+      {
+        "name": "245bc4c430d393f74fbe7b13325e30dbde9fb0745e50caad57c446c93d20096b",
+        "size": 2341058
+      },
+      {
+        "name": "85b420239efa1132c41cea0065452a40ebc20c6f8e0b132a5b2f5848360973ec",
+        "size": 2908900
+      },
+      {
+        "name": "8e2006bb5931a520f3c7009fe278d1ebb87eb72c3ff92a50c30e90f1b8cf3e60",
+        "size": 3030712
+      },
+      {
+        "name": "e75c8c407ea31ba399ab4109f28dd18c4c68303d8d86cc275432820c42ce3649",
+        "size": 2804
+      }
+    ]
+
+HEAD {path}/{type}/{name}
+=========================
+
+Returns "200 OK" if the blob with the given name and type is stored in
+the repository, "404 not found" otherwise. If the blob exists, the HTTP
+header ``Content-Length`` is set to the file size.
+
+GET {path}/{type}/{name}
+========================
+
+Returns the content of the blob with the given name and type if it is
+stored in the repository, "404 not found" otherwise.
+
+If the request specifies a partial read with a Range header field, then
+the status code of the response is 206 instead of 200 and the response
+only contains the specified range.
+
+Response format: binary/octet-stream
+
+POST {path}/{type}/{name}
+=========================
+
+Saves the content of the request body as a blob with the given name and
+type, an HTTP error otherwise.
+
+Request format: binary/octet-stream
+
+DELETE {path}/{type}/{name}
+===========================
+
+Returns "200 OK" if the blob with the given name and type has been
+deleted from the repository, an HTTP error otherwise.
+
+