Architectural Notes

Notes generally relevant to most/all endpoints

BETA: The /v3 API endpoints are considered to be beta at the time of this writing. They are subject to change, and our team is open to feedback as we evolve these to maximize expressiveness and ease-of-use.

REST-ish Philosophy

While the platform APIs make a notional attempt to follow RESTful principles, we prioritized ease of use over strict adherence in a number of places. This is particularly relevant in the areas touching configuration state where the REST interface is intended to exist in parallel with a git-centric interface. After earlier experiments with other designs, the REST API in these areas is intended to convey the intuition of manipulating files in git rather than editing entries in a datastore and we treat the files as they exist in git as the ultimate upstream source of state.

Asynchronous Unless Otherwise Specified

Several of the APIs, e.g. creating Workspaces, merging branches to the production (main) branch or running a taskset, represent actions that can take O(10) and sometimes O(100) seconds to complete given the high latency nature of systems with which they interface. Unless otherwise specified, the APIs here will return when the action is started, but well before the action is ended. Where practical, the documentation specifies the endpoint that should be used to poll for completion and error state.

Names vs IDs

For Kubernetes users, the majority of the object model will be rapidly recognizable as K8s custom resources. By convention, Kubernetes resources use the field "name" as a unique key within the scope of their "kind" (database table) and "namespace" (database instance). While you may notice in the REST API that a number of resources expose an "id" field, this field should not be considered a long term stable key, i.e. it may change from time to time while the "name" remains constant. In general, if there is a "name" field on the resource then callers should use this as a key when interfacing with external systems and ignore the "id" field. (It may even be deprecated in future versions of the API.)

The Session Branch

A fairly large surface area of the REST API is under the .../branches/ endpoint, a thin shim on top of file manipulation in git. This area deviates from REST principles to prioritize transparency of the GitOps flow of upstream state at the heart of configuring resources on the platform. Typical flows involve posting a file to a branch and then merging that branch with main (or some other branch that is set to sync with production). As a convenience, a "--" can be used in these endpoints instead of a branch name. This is called the "Session Branch Alias," and signals the back end to lazily create a branch from main with a unique name and store that name in a session cookie. The branch is not actually created in the git repository until there is a valid commit, but all GET requests to content on that branch will return valid content (from main). See the examples section for details on how this convenience is used.