docs: Add service-to-service API standards

custom-words.txt

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

docs/architecture/adr/0035-service-oriented-architecture.md

@@ -113,11 +113,11 @@ The rules:
 1. Services `MUST` document their APIs in [OpenAPI format](https://www.openapis.org/). A
    **service-to-service API** — one whose callers are other Bitwarden services, rather than the
    clients and third parties that call the private and public APIs today — `MUST` additionally
-   conform to the forthcoming **Service-to-Service API Standards**.
+   conform to the [Service-to-Service API Standards](../server/apis/index.md).
 1. Services `SHOULD NOT` make breaking changes.
    - If the changes that need to be made _would_ be breaking to a service-to-service API, such
-     services `SHOULD` follow the API versioning process as outlined by the forthcoming
-     Service-to-Service API Standards.
+     services `SHOULD` follow the API versioning process as outlined by the
+     [Service-to-Service API Standards](../server/apis/breaking-changes-and-versioning.md).
    - Fixing bugs, including security issues, are not subject to this rule and `MUST` be fixed "in
      place".
 1. Services `MUST` provide a **service client** for consumers.
@@ -185,8 +185,8 @@ The rules:
 
 ### Plan
 
-- Publish the **Service-to-Service API Standards**. Rules 4 and 5 reference it normatively and it
-  does not exist yet on this site.
+- Publish the [Service-to-Service API Standards](../server/apis/index.md), which rules 4 and 5
+  reference normatively.
 - Publish a client strategy page covering how a service client is generated, wrapped, versioned, and
   cached.
 - Publish a service identity and context page covering service-to-service authentication,

docs/architecture/adr/0036-service-to-service-api-standards.md

@@ -119,9 +119,10 @@ path. To be useful, the standards have to be comprehensive. At a minimum, they n
 Chosen option: **Documented standards**.
 
 Service-to-service APIs `MUST` conform to a comprehensive, documented set of standards covering, at
-a minimum, the topics listed above. The standards will be published separately as a living
-reference: their rules evolve by pull request without superseding this decision, and this ADR is
-superseded only if the decision to have documented standards itself changes.
+a minimum, the topics listed above. The standards are published separately as a
+[living reference](../server/apis/index.md): their rules evolve by pull request without superseding
+this decision, and this ADR is superseded only if the decision to have documented standards itself
+changes.
 
 ### Positive consequences
 

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
+
+Notation follows the [APIs index](./index.md#notation).
+
+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.
+- Unlike the CRUD APIs, _actions_ impose no restrictions on the shape of the JSON posted.
+- A field that changes only through actions, such as a status whose transitions follow business
+  rules, `MUST` be read-only, so that no update can bypass the action.
+
+```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!"
+}
+```
+
+**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.                                                       |

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

@@ -0,0 +1,73 @@
+# Advanced queries
+
+Notation follows the [APIs index](./index.md#notation).
+
+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`.
+
+JSON Logic is used rather than OData's `$filter` because:
+
+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 premium users whose key derivation function (KDF) iterations are below the current minimum:
+
+```http
+POST /api/v1/users:search?page[size]=50&sort=-creationDate
+Accept: application/json
+Content-Type: application/json
+```
+
+```json
+{
+  "filter": {
+    "and": [{ "<": [{ "var": "kdfIterations" }, 600000] }, { "==": [{ "var": "premium" }, true] }]
+  }
+}
+```
+
+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/targeting.md).
+
+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,101 @@
+# API paths
+
+Notation follows the [APIs index](./index.md#notation).
+
+API paths `MUST` use **lowercase "kebab-case"** and conform as follows:
+
+1. The first one or more elements 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", such as `users`.
+   [Bulk-processing](./bulk-operations/index.md) APIs are an exception to this rule.
+   - APIs that create resources stop here.
+4. If the API targets a specific resource, as an update or delete does, 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.
+
+**Examples**
+
+```text
+/api/v1/users
+/api/v1/users/123
+/api/v1/users/123/devices
+```
+
+Paths `SHOULD` be traversable. If `GET /api/v1/users/123/devices/456` returns the details about
+device 456 of user 123, then every parent path would resolve as follows:
+
+- `GET /api/v1/users/123/devices` should return all devices of user 123.
+- `GET /api/v1/users/123` should return details about user 123.
+- `GET /api/v1/users` should return all users.
+
+Not every parent path has to exist as a callable API, and a caller is not necessarily authorized to
+call one that does. Traversable paths show how paths fit together, and how they _would_ resolve if
+APIs existed for every parent path.
+
+:::note
+
+2. The version is in the path because it is then visible in logs, traces, routing rules, and curl
+   commands, needs no content negotiation to read, and lets two versions coexist behind one host.
+   Header and media-type versioning are both defensible but harder to operate.
+
+:::
+
+## Which identifiers belong in the path
+
+Every request targets a **subject** and runs inside a **scope**:
+
+1. The **subject** is what the request acts on, which is a resource or a collection of resources. It
+   `MUST` be named in the path.
+2. 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, which a forthcoming standard will cover.
+
+**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.
+
+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.
+
+:::note
+
+2. The scope stays out of the path because 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.
+
+:::
+
+## 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 let the caller specify which organizations to return data for, as in
+  `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,40 @@
+# Breaking changes and versioning
+
+Notation follows the [APIs index](./index.md#notation).
+
+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 or incomplete. 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.
+6. Returning fewer results for the same request, such as introducing paging or lowering a default
+   page size.
+
+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, including security issues, `MUST` 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).
+
+Service-to-service APIs are versioned, unlike the existing public API, because 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.
+
+## Adding values to constrained fields
+
+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.

docs/architecture/server/apis/bulk-operations/all-or-nothing-and-best-effort.md

@@ -0,0 +1,26 @@
+# All-or-nothing and best-effort
+
+Notation follows the [APIs index](../index.md#notation).
+
+- **All-or-nothing:** no resource changes unless every resource succeeds. If any resource fails, the
+  request fails and the response reports every failure, not just the first.
+- **Best-effort:** each resource succeeds or fails on its own. One resource's failure `MUST NOT`
+  prevent or undo another's success.
+
+A service `MAY` support either mode or both. Callers choose with the `atomic` query parameter:
+`atomic=true` for all-or-nothing, `atomic=false` for best-effort.
+
+- A service that supports both modes `MUST` default to all-or-nothing.
+- Every bulk API `MUST` recognize `atomic`, even if it supports only one mode, and `MUST` reject
+  with `422` a value it does not support. Ignoring the parameter would change the outcome rather
+  than merely do less - see
+  [Unrecognized fields, query parameters, and headers](../unrecognized-fields-query-parameters-and-headers.md).
+- Problems with the request itself - a malformed `filter`, too many items, both `ids` and `filter` -
+  are not per-resource failures. They reject the whole request in either mode, before any resource
+  is processed.
+
+**Example**
+
+```http
+POST /api/v1/users:bulk-delete?atomic=false
+```

docs/architecture/server/apis/bulk-operations/bulk-actions.md

@@ -0,0 +1,64 @@
+# Bulk actions
+
+Notation follows the [APIs index](../index.md#notation).
+
+Bulk actions are the equivalent of invoking an [action](../acting-upon-resources.md) upon each
+targeted resource.
+
+- API path `MUST` follow the pattern `/api/v1/{resource plural}:bulk-{action}`, where `{action}` is
+  the name of the single-resource action - e.g. `/api/v1/users:bulk-send-email` for
+  `/api/v1/users/{id}/actions/send-email`.
+- Because bulk actions share a namespace with the other bulk operations, actions `MUST NOT` be named
+  `create`, `update`, `replace`, or `delete`.
+- `data` holds exactly what the single-resource action would accept as its body, and is applied to
+  every targeted resource. It `MAY` be omitted if the action takes no body.
+
+**Example**
+
+```http
+POST /api/v1/users:bulk-send-email
+Accept: application/json
+Content-Type: application/json
+```
+
+```json
+{
+  "ids": ["62bed180-1f78-45d4-8a56-c996936a2947", "cacba8c1-29fa-4018-8950-acd400ec76b7"],
+  "data": {
+    "subject": "Hello",
+    "body": "World!"
+  }
+}
+```
+
+## Input that differs per resource
+
+Actions that require per-resource bodies specify the data as an array.
+
+- It `MUST` be used with `ids`, not `filter`, and `MUST` be the same length. `data[n]` is the body
+  for `ids[n]`.
+- A failure is reported against `/data/{n}`.
+
+**Example**
+
+```http
+POST /api/v1/users:bulk-send-email
+Accept: application/json
+Content-Type: application/json
+```
+
+```json
+{
+  "ids": ["62bed180-1f78-45d4-8a56-c996936a2947", "cacba8c1-29fa-4018-8950-acd400ec76b7"],
+  "data": [
+    {
+      "subject": "Hello.",
+      "body": "Hi, John!"
+    },
+    {
+      "subject": "Hello",
+      "body": "Hi, Mary!"
+    }
+  ]
+}
+```