Skip to main content

APIs

Audience: Developers and AI agents designing or implementing service-to-service APIs.

Notation​

The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.

Text in braces, such as {resource plural}, {id}, or {action}, is a placeholder for a value.

A colon after a collection path, as in /api/v1/users:search or /api/v1/users:bulk-delete, names an operation on the collection as a whole.

Examples​

No service implements these standards yet, so the examples are illustrative rather than taken from running code. They are modeled on existing data in the server repository, such as users in src/Core/Entities/User.cs, devices in src/Core/Entities/Device.cs, and groups in src/Core/AdminConsole/Entities/Group.cs.

Scope​

These standards apply to service-to-service APIs developed in new services. A service-to-service API is one that a Bitwarden service calls on another.

They do not apply to:

  • Existing Bitwarden APIs, which predate these standards and are not being changed to conform. This includes the public API and the APIs our own clients call.
  • APIs that implement an external standard, such as webhooks, OpenTelemetry, or health checks.

Overview​

ADR-0036 requires service-to-service APIs to conform to a documented set of standards. These are those standards.

As set out in ADR-0039, the standards are self-contained: every rule is stated here, and no rule is incorporated by reference. Where an IETF RFC covers a topic, the standards adopt it as published, and where they keep their own answer instead, they record why. Conventions taken from other specifications are credited to their source.

General​

These APIs borrow REST's vocabulary of resources and self-descriptive messages, but they are not RESTful. Each API is versioned on its own, so operations on the same resource can live at different paths, and responses carry identifiers rather than hyperlinks.

In general, these APIs are resource-oriented and do one of 4 things:

This is the familiar CRUD paradigm and, while there will always be exceptions, developers SHOULD strive to think in these terms for every API created. Both for simplicity and consistency.

We do recognize, however, that not every API will fit cleanly into this CRUD paradigm. APIs that “act” upon resources and bulk-processing APIs are two notable examples. Standards for every pattern are described below.

Well-defined APIs​

A well-defined API spells out exactly how it should be called and what the caller can expect in return - for both the happy path and possible error paths. Developers are encouraged to think in terms of resources and be on guard against API proliferation that can result from over-tailoring APIs to the unique needs of this caller or that.

In general, it is better to have one API per resource that can be called two different ways, such as through query parameters, than two APIs that can only be called one way.

Authentication and authorization​

How a caller proves its identity, how a service authorizes an operation, and how the current organization travels with a request are the subject of a forthcoming standard.

Contents​

Contracts​

Payloads and responses​

Operations​

Querying​

Bulk and asynchronous work​