API docs rewrite.

Having the whole API in a single file was starting to feel very cramped and constraining. This rewrite breaks it out into sections; as a side effect, the docs are now about 2.5x as long as they were, as the rewrite allows more space for each idea without crowding the page.

The docs are best read by running `tools/docs-api`.

1 files changed, 57 insertions, 0 deletions

diff --git a/docs/api/basics.md b/docs/api/basics.md
new file mode 100644
index 0000000..271a269
--- /dev/null
+++ b/docs/api/basics.md
@@ -0,0 +1,57 @@
+# The basics
+
+The API is exposed as a collection of HTTP endpoints that accept JSON and return JSON on success, with exceptions as noted in the documentation for each endpoint.
+
+
+## Path parameters
+
+Many API endpoints accept one or more parameters via the URL's path element. Each parameter in the documentation is described using a placeholder, consisting of a leading full colon followed by a label (for example, `:example`).
+
+Each endpoint's documentation describes the expected type and value of each parameter it accepts.
+
+
+## Types
+
+Each endpoint documents the types of the fields in each request or response. The types consist of:
+
+* `integer`: a number, with no decimal part, representing a 64-bit unsigned integer.
+* `string`: any string.
+* `timestamp`: a string containing an [RFC 3339] timestamp.
+* `object`: a nested structure, which has its own schema.
+* `array of TYPE`: an array, whose elements follow the `TYPE` schema (ex. `array of object`).
+
+[RFC 3339]: https://www.rfc-editor.org/rfc/rfc3339
+
+
+## Request bodies
+
+Requests that require a JSON body must include a `content-type: application/json` header.
+
+For requests that take a JSON body, if the body does not match the required schema, the endpoint will return a `422 Unprocessable Entity` response, instead of the responses documented for that endpoint.
+
+
+## Response bodies
+
+In general, API endpoints that return data do so as `application/json` documents, containing either a single object, or a list of objects. Each endpoint's documentation includes the response schema.
+
+A small number of endpoints return data in other formats. These exceptions are included in the relevant endpoints' documentation.
+
+
+## Status codes
+
+This API uses HTTP status codes to report success or failure. Each endpoint documents the status codes it may return.
+
+In addition to the documented status codes for each endpoint, any endpoint may return the following status codes:
+
+* `401 Unauthorized`, as described under [authentication](./authentication.md#authentication-failures).
+
+* `422 Unprocessable Entity`, as described under [request bodies](#request-bodies).
+
+* `503 Service Unavailable`, as described under [initial setup](./initial-setup.md#requests-before-setup-completed).
+
+* `500 Internal Server Error`, if there was an unexpected problem handling the request. The server will record information about the error to its own standard output.
+
+
+## Errors
+
+When the server returns an error (any response whose status code is 400 or greater), the response body is freeform text (specifically, `text/plain`), which may be shown to the user, logged, or otherwise handled. Programmatic action should rely on the documented status codes, and not on the response body.