[mike-gorman-bitwarden]

🎟️ Tracking

Follow-up to ADR-0036 (#865).

📔 Objective

Adds the service-to-service API standards under Server Architecture: an index page that links to one page per topic, covering contracts, payloads, creating, reading, updating, deleting, acting upon, and bulk processing resources.

What's different

If you have worked on the existing Api server, here is what changes when you build or call an API
that follows these standards. Comparisons are taken from the Api OpenAPI specs (internal: 632
operations; public: 28 operations). The standards apply only to new service-to-service APIs in new
services. Nothing existing is changing.

At a glance

Area	Existing APIs today	APIs that follow the standards
Versioning	Unversioned paths (/ciphers/{id}).	Version in the path (/api/v1/users/{id}), with rules for breaking changes and Deprecation/Sunset headers.
Organization	Usually in the path: 146 of 489 internal paths carry {orgId} (/organizations/{orgId}/users).	Travels with the request as context. The path names only what is acted on (/api/v1/users).
Methods	POST often stands in for other verbs: 46 paths delete through POST/PUT .../delete, and 36 paths accept both PUT and POST.	DELETE deletes, PUT replaces. Anything else is an action (POST .../{id}/actions/{action}) or a bulk operation (POST ...:bulk-delete).
Payloads	Flat models with an object type string ("object": "cipher").	Resources in a data envelope with id, type, and attributes; metadata in meta.
Read many	Mostly unpaged. See below.	Paged, filtered, sorted, and trimmed with standard query parameters. See below.
Errors	ErrorResponseModel: one message plus a validationErrors map, returned as 400.	An errors array; each error has a stable code, status, title, detail, id, and a source naming the field, parameter, or header. Validation failures are 422.
Enumerations	Integers (72 of 77 enums), so 2 has to be looked up.	Uppercase strings (CONFIRMED), compared case-insensitively.
Field names	creationDate, revisionDate, organizationId, isTrusted.	createdAt, updatedAt, createdBy; no Id suffix for references; no is prefix for booleans.
Concurrency	Endpoint-specific, such as lastKnownRevisionDate on cipher updates.	A version field on resources that detect conflicts; a stale version returns 409.
Validation	Varies by endpoint.	Every request is validated in full before processing, and all failures are reported at once.

Example: reading many resources

Most list endpoints today return everything in one response. Of the 69 internal GET endpoints that
return a list, 12 accept a paging parameter, and 11 of those are event logs. Paging, where it
exists, uses an opaque continuationToken with a fixed page size of 50 (only /notifications
accepts a pageSize). There are no totals, and filtering and sorting are not standardized: each
endpoint defines its own parameters, such as start, end, status, or includeGroups.

Today: list an organization's members. Every member comes back in one response.

GET /organizations/{orgId}/users

{
  "object": "list",
  "data": [
    {
      "object": "organizationUserUserDetails",
      "id": "…",
      "email": "alice@example.com",
      "status": 2
    }
  ],
  "continuationToken": null
}

With the standards: the same request, paged, filtered, and sorted with standard parameters. The
organization comes from the request context.

GET /api/v1/users?filter[status]=CONFIRMED&sort=email&page[number]=1&page[size]=50

{
  "data": [
    {
      "attributes": {
        "email": "alice@example.com",
        "status": "CONFIRMED"
      },
      "id": "…",
      "type": "user"
    }
  ],
  "meta": {
    "pageCount": 9,
    "pageNumber": 1,
    "pageSize": 50,
    "totalCount": 402
  }
}

What changes for you:

• Paging is the norm. Read-many APIs SHOULD page. The caller chooses the page size, up to a
  maximum the API documents.
• Two paging styles. Offset paging (page[number], page[size]) can report page and total
  counts. Cursor paging (page[size], page[after]) works like today's continuation token, but
  meta says explicitly whether more results follow (hasMore) instead of leaving the caller to
  infer it from a null token.
• One way to filter, sort, and trim. filter[{field}] with wildcards, multiple values, and
  ranges; sort=-createdAt; and fields=email,status to return only some fields. The OpenAPI spec
  lists which fields support each.
• Richer queries move to the body. POST /api/v1/users:search takes a JSON Logic expression for
  AND/OR combinations that do not fit in a URL, and returns the same shape as a read-many
  request.
• Unsupported parameters are rejected, not ignored. A filter, sort, or paging parameter the API
  does not support returns 422, so a caller never silently receives unfiltered or unsorted data.

What does not change

• Existing public and client-facing APIs keep their current conventions.
• Handlers still take and return plain models. The envelope, paging metadata, and error format are
  meant to be produced by Bitwarden.Server.Sdk rather than written by hand.

[cloudflare-workers-and-pages]

Deploying contributing-docs with    Cloudflare Pages

Latest commit:	c0f5ba4
Status:	✅  Deploy successful!
Preview URL:	https://a7768609.contributing-docs.pages.dev
Branch Preview URL:	https://docs-service-to-service-api.contributing-docs.pages.dev

View logs

[audreyality]

🎨 The category is very long. I'd consider whether introducing a second grouping, consistent with the TOC, would help with organizing.

[mike-gorman-bitwarden]

Sorry, I don't know what you mean by "The category is very long."

[mike-gorman-bitwarden]

Do you mean the child pages?

[audreyality]

Yeah, the page list within the "apis" category has a ton of entries in it. It would be helpful if the grouping in the sidebar reflected the grouping in the index.

[withinfocus]

A great first version of this!