docs: Add service-to-service API standards

custom-words.txt

@@ -43,6 +43,7 @@ Iterm
 Jetpack
 jslib
 jumpcloud
+kebab
 keychain
 keypair
 keyserver

docs/architecture/server/apis/_category_.yml

@@ -0,0 +1,2 @@
+label: "APIs"
+position: 1

docs/architecture/server/apis/acting-upon-resources.md

@@ -0,0 +1,37 @@
+# Acting upon resources
+
+Operations that do not fit creating, reading, updating, or deleting a resource are exposed as
+**actions** on the resource. Modeling each operation as a distinct API makes it easy to discover,
+and lets it be authorized independently of the standard update.
+
+- HTTP verb `MUST` be `POST`.
+- API path `SHOULD` follow the pattern `/api/v1/{resource plural}/{id}/actions/{action}`, with the
+  action named in kebab-case.
+
+```http
+POST /api/v1/users/62bed180-1f78-45d4-8a56-c996936a2947/actions/send-email
+Accept: application/json
+Content-Type: application/json
+```
+
+```json
+{
+  "subject": "Hello",
+  "body": "World!"
+}
+```
+
+> Unlike the CRUD APIs, _actions_ impose no restrictions on the shape of the JSON posted.
+
+**Success responses**
+
+Upon success, APIs `SHOULD` return `204` but `MAY` return `200` or `202`.
+
+| Status           | Description                | Response                                                       |
+| ---------------- | -------------------------- | -------------------------------------------------------------- |
+| `200 OK`         | The action was successful. | The latest representation of the resource.                     |
+| `202 Accepted`   | The action is scheduled.   | The [job](./jobs.md) that was scheduled to execute the action. |
+| `204 No Content` | The action was successful. | Nothing.                                                       |
+
+> A field that changes only through actions (e.g. a status whose transitions follow business rules)
+> `MUST` be read-only, so that no update can bypass the action.

docs/architecture/server/apis/advanced-queries.md

@@ -0,0 +1,76 @@
+# Advanced queries
+
+The `filter` query parameters cover simple predicates, but they cannot express arbitrary `AND` and
+`OR` combinations, and a long expression will exceed the practical limit on URL length. APIs that
+need richer queries `MUST` expose a **search** operation that carries the expression in the request
+body.
+
+- HTTP verb `MUST` be `POST`.
+- API path `MUST` follow the pattern `/api/v1/{resource plural}:search`.
+
+The expression is written in [JSON Logic](https://jsonlogic.com/) and placed in a top-level `filter`
+field. JSON Logic is adopted for its notation only. Its full operator set includes control flow,
+iteration, and arithmetic, none of which belong in a query, so only the following operators are
+supported:
+
+| Operator             | Meaning                                             |
+| -------------------- | --------------------------------------------------- |
+| `var`                | Reference a field of the resource.                  |
+| `==`, `!=`           | Equal, not equal.                                   |
+| `>`, `>=`, `<`, `<=` | Numeric and date comparison.                        |
+| `in`                 | Membership in a list, or a substring match.         |
+| `and`, `or`          | Boolean composition, each taking two or more terms. |
+| `!`                  | Negation.                                           |
+
+A request that uses any other operator, or references a field the API does not support, `MUST` be
+rejected with `422`.
+
+:::faq[Why are we standardizing on JSON Logic instead of OData?]
+
+1. OData's `$filter` is a string expression language, so both building and parsing it require string
+   handling where JSON is already right there.
+2. Composing a filter by concatenating strings means quoting and escaping, which is how injection
+   bugs happen. Composing a JSON object does not.
+3. OData brings a great deal more than filtering - metadata documents, `$expand`, batch, its own
+   conventions - and we only want the filtering.
+
+:::
+
+**Example**
+
+Find active or invited users whose KDF iterations are below the current minimum:
+
+```http
+POST /api/v1/users:search?page[size]=50&sort=-createdAt
+Accept: application/json
+Content-Type: application/json
+```
+
+```json
+{
+  "filter": {
+    "and": [
+      { "<": [{ "var": "kdfIterations" }, 600000] },
+      { "in": [{ "var": "status" }, ["ACTIVE", "INVITED"]] }
+    ]
+  }
+}
+```
+
+The response `MUST` be identical in shape to the equivalent
+[read-many](./reading-resources.md#read-many) request.
+
+[Learn more about JSON Logic](https://jsonlogic.com/)
+
+**Success responses**
+
+Upon success, APIs `MUST` return `200`.
+
+| Status   | Description                | Response                                  |
+| -------- | -------------------------- | ----------------------------------------- |
+| `200 OK` | The search was successful. | The matching resources, paged and sorted. |
+
+The same notation selects resources for [bulk operations](./bulk-operations.md#targeting).
+
+The `:search` syntax is credited to [Google AIP-136](https://google.aip.dev/136), and the query
+notation to [JSON Logic](https://jsonlogic.com/).

docs/architecture/server/apis/api-paths.md

@@ -0,0 +1,103 @@
+# API paths
+
+API paths `MUST` use **lowercase "kebab-case"** and conform as follows:
+
+1. The first element(s) of the API path `MUST` be a namespace. By default, the namespace `SHOULD` be
+   `api`.
+2. The next element of the API path `MUST` be the version number starting with `v1`.
+3. The next element of the API path `MUST` specify the resource or resources it targets. For
+   resource-oriented APIs, this element `SHOULD` be the "resource plural" (e.g. `users`).
+   [Bulk-processing](./bulk-operations.md) APIs are an exception to this rule.
+   - APIs that create resources stop here.
+4. If the API targets a specific resource (e.g. update or delete), the next element of the API path
+   `SHOULD` be the ID of the resource it targets.
+5. Additional elements `MAY` be specified to target sub-resources.
+
+:::faq[Why versioning in the path?]
+
+It is visible in logs, traces, routing rules and curl commands; it needs no content negotiation to
+read; and it lets two versions coexist behind one host. Header and media-type versioning are both
+defensible but harder to operate.
+
+:::
+
+**Examples**
+
+```text
+/api/v1/users
+/api/v1/users/123
+/api/v1/users/123/addresses
+```
+
+Paths `SHOULD` be traversable. If `GET /api/v1/users/123/addresses/456` returns the details about
+address 456 of user 123, then every parent path would resolve as follows:
+
+- `GET /api/v1/users/123/addresses` should return all addresses of user 123.
+- `GET /api/v1/users/123` should return details about user 123.
+- `GET /api/v1/users` should return all users.
+
+:::tip
+
+To be clear, we are not saying every “parent path” must actually exist as a callable API, or even
+that the current user should be authorized to call them. We are only trying to show how API paths
+should be cohesive, and how they _would_ resolve if APIs existed for every parent path.
+
+:::
+
+## Which identifiers belong in the path
+
+Every request targets a **subject** and runs inside a **scope**:
+
+- The **subject** is what the request acts on (i.e. a resource or a collection of resources). It
+  `MUST` be named in the path.
+- The **scope** is what the request runs inside - the current organization, the current user. It
+  `MUST NOT` be named in the path; it travels as context.
+
+That is the whole of the path rule. A path says what is acted on (or fetched). It does not say what
+a call returns: which parts of the scope an operation requires, permits or refuses is declared by
+the operation, and belongs to authentication and authorization (standard forthcoming).
+
+**Examples**
+
+| Path                        | Subject                  |
+| --------------------------- | ------------------------ |
+| `GET /api/v1/users`         | users                    |
+| `GET /api/v1/users/123`     | user 123                 |
+| `GET /api/v1/users/current` | the user the scope names |
+
+`current` `SHOULD` be used where the subject is whatever the scope names, rather than repeating an
+identifier the caller has already supplied.
+
+:::faq[Why keep the scope out?]
+
+An identifier in a path is something a caller can try other values of, and a path that accepts one
+must prove on every request that this caller may use this value. A scope taken from context is
+established once, where the caller is authenticated. It also keeps one path for a resource that can
+belong to more than one kind of owner.
+
+:::
+
+Callers `SHOULD` send the current organization and the current user on every request where each
+exists. Two services may publish the same path and declare different things about the scope - one
+`GET /api/v1/organizations` requiring a user and returning theirs, another requiring none and
+returning all. Both name the same subject; the path is not what distinguishes them.
+
+## Working across several scopes
+
+A caller that reaches several organizations does not turn the organization into a subject, nor does
+it necessarily mean one call per organization. Options include:
+
+- If it is somewhat rare and typically only "a few", then making N calls with a different
+  organization in context is probably fine.
+- The API may be enhanced to allow the caller to specify what organizations to return data for (e.g.
+  `GET /api/v1/users?filter[organization]=123,456,789`).
+- An [advanced query](./advanced-queries.md) may be used where the list travels in the body rather
+  than the URL.
+
+An operation can also be declared so that supplying less scope means more.
+
+For example, `GET /api/v1/users` called with a user and an organization in context returns every
+user within the specified organization, but that _same_ API called with only a user in context might
+return every user for every organization the user is a member of. Whether it behaves that way is the
+operation's declaration rather than the path's - and the option exists without any of these patterns
+putting the organization in the path.

docs/architecture/server/apis/breaking-changes-and-versioning.md

@@ -0,0 +1,43 @@
+# Breaking changes and versioning
+
+APIs `SHOULD NOT` make **breaking changes**. A breaking change is any change that causes a request
+that is valid today to be rejected tomorrow, or a response that a caller can process today to become
+unprocessable. In practice, that means:
+
+1. Adding a new, required field.
+2. Making an optional field required.
+3. Changing the datatype of a field.
+4. Adding additional constraints to a field.
+5. Removing a field from a response.
+
+The verb is `SHOULD NOT` rather than `MUST NOT` because these are service-to-service APIs and we own
+every caller. A team `MAY` make a breaking change in place when it can account for every caller -
+either because the change has been coordinated with them, or because the rejection surfaces
+somewhere the caller or the user can act on it.
+
+Bugs, however, `SHOULD` be fixed "in place", without creating new versions of the API, even if the
+changes would technically be considered breaking changes.
+
+Otherwise, if changes need to be made that _would_ be breaking changes, a new version of the API
+`MUST` be created and the old one [deprecated](./deprecation.md).
+
+:::faq[Why are service-to-service APIs versioned? Public APIs aren't.]
+
+We feel strongly that service-to-service APIs should be formally versioned. Without formal
+versioning, every change must be additive, which means the shape can never change and every new
+field is optional. Contracts constrained like that get weaker over time, and what we _want_ to
+express eventually cannot be expressed, because we have committed ourselves to "additive changes
+only". This rules out adopting the existing public API conventions, which are expressly unversioned.
+
+:::
+
+:::note
+
+Adding a value to a constrained field deserves a second look. It is additive, so it is not a
+breaking change by the definition above, and a caller that treats the field as an open string is
+unaffected. But a generated client that deserializes the field into a closed enumeration will fail
+on a value it has never seen - and it will fail at the client, on a change that looked safe from the
+service. Consider whether the callers of that field are tolerant of unknown values before adding
+one.
+
+:::