Add documentation about read-only mode in API.

Fixes #9316

docs/topics/api/overview.rst

@@ -89,6 +89,28 @@ constants are as follows:
     ========================  =========================================================
 
 
+~~~~~~~~~~~~~~~~~
+Maintainance Mode
+~~~~~~~~~~~~~~~~~
+
+When returning ``HTTP 503 Service Unavailable`` responses the API may be in
+read-only mode. This means that for a short period of time we do not allow any
+write requests, this includes ``POST``, ``PATCH`` and ``DELETE`` requests.
+
+In case we are in read-only mode, the following behavior can be observed:
+
+  * ``GET`` requests behave normal
+  * ``POST``, ``PUT`` and ``DELETE`` requests return 503 with a json response that contains a localized error message
+  * A custom ``X-AMO-Read-Only`` header is set to ``true``
+  * A ``Retry-After`` header may be set, it's not a requirement though and can be omitted
+
+In case we are not in read-only mode, the following (standard) behavior can be observed:
+
+  * ``GET``, ``POST``, ``PUT``, ``DELETE`` requests behave normal again
+  * ``X-AMO-Read-Only`` header is set to ``false``
+
+So, in case of a ``503`` HTTP response you can always check the ``X-AMO-Read-Only`` header to behave appropriately.
+
 ~~~~~~~~~~
 Pagination
 ~~~~~~~~~~