docs: Add ADR 0039 - Base API standards on IETF RFCs

[mike-gorman-bitwarden]

🎟️ Tracking

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

📔 Objective

Adds ADR-0039, "Base API standards on IETF RFCs", with status Proposed. Decides what the service-to-service API standards are built on: our own standards, adopting an IETF RFC wherever one covers a topic and recording why wherever they don't.

[cloudflare-workers-and-pages]

Deploying contributing-docs with    Cloudflare Pages

Latest commit:	ccb2015
Status:	✅  Deploy successful!
Preview URL:	https://1288669c.contributing-docs.pages.dev
Branch Preview URL:	https://docs-adr-0039-base-api-stand.contributing-docs.pages.dev

View logs

[Hinton]

Can you expand on all the metrics? How does generated clients work for JSON:API? They specifically removed that.

[mike-gorman-bitwarden]

A definition of what each row's consideration or requirement means has been added below this table.

How does generated clients work for JSON:API? They specifically removed that.

I am not sure what you mean. Clients are generated from OpenAPI specs, typically via OpenAPI Generator or NSwag.

These client generators can generate clients from any OpenAPI spec, including ones that are based on JSON:API-style APIs. But I want to make it clear that this ADR does not propose we standardize on JSON:API. It says we may borrow from it where we see fit but nothing about this ADR says we will standardize on JSON:API or use anything from it.

[Hinton]

The JSON:API library for c# removed support for OpenApi.

[mike-gorman-bitwarden]

Oh, I see what you're talking about now: JsonApiDotNetCore

That was basically a convenience library someone created for people that wanted to expose their data model directly as JSON:API style resources. That is not what we are doing and is not needed. And, as I mentioned before, this ADR does not endorse or reject any "idea" borrowed from the JSON:API spec.

Even if we do adopt many JSON:API conventions, at the end of the day, they are just C# classes/records with a particular shape that Swashbuckle/NSwag/Etc. handle just like they would any other C# types.

[audreyality]

🤔 It seems to me that this ADR dismisses all established standards because none of them provide a comprehensive outlook on all possible operations that we can perform. The full sequence of ADRs attempt to span all of our services, looking for a "silver bullet". Since we cannot find a standard that satisfies the full conceivable set of operations, we're electing instead to create our own.

💭 Have we considered an option that classifies services according to their purpose? From there, we could adopt standards suited to specific purposes in their entirety.

For example, say we break down the categories as follows:

• CRUD-style services that work on individual objects in a resource/RESTful style.
• E2E encrypted services that are highly specialized, mostly opaque BLOBs.
• Analytics services that process unencrypted records into reports.

The CRUD-style services might choose JSON:API; the E2E encrypted services might have a fully-specified custom protocol; the analytics services might use GraphQL. (Reminder: These are examples; I'm not proposing specific protocols. I'm proposing a different set of categories and follow-on ADRs that could evaluate the standards this ADR rejects on a case-by-case basis.)

The primary benefit of this approach is that we invest minimal effort in specifying common operations (CRUD, analytics), and concentrate our resources on the operations that are singular to our product (E2E encryption and zero-knowledge).