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.