Ids, handles and aliases

The API makes extensive use of three different types of fields to identify and reference resources. Each one follows different rules and is meant for different purposes.

​

IDs

IDs are UUIDs (Universally Unique Identifiers) and follow their standard format. They are randomly generated by the platform when a resource is created and cannot be changed.

Their purpose is to uniquely identify resources in an invariant way so that the platform can keep track of them throughout their whole lifetime. They are not intended to be used to interact with the API and should only be referenced in debugging contexts.

Example of an ID

986b0cc0-e559-47a1-8226-bedf5002371f

​

Handles

Handles are hyphen-separated lowercase alphanumeric characters, following a custom format. They are usually user-specified and can be changed at any time, although in some situations they may default to the ID of the resource.

Their purpose is to uniquely identify resources in a human-friendly way, while maintaining a restrictive, URL-friendly format. They are the only valid way to reference resources in path and body parameters.

Example of a handle

th1s-1s-a-handle

​

Local and global handles

Although handles allow us to uniquely identify resources, some of them are not globally unique and are instead local to a certain context.

For example, two API keys may have the same handle as long as they belong to different users, each being uniquely identifyable in its own context.

Example of two API keys of different users with the same handle

/users/alice/keys/main
/users/bob/keys/main

​

Composite handles

Some resources are thightly related to a different resource but not nested under it, in those cases composite handles are used to uniquely identify resources.

For example, two spaces may have the same handle as long as they belong to different owners, each being uniquely identifyable by their composite handle.

Example of two spaces of different owners with the same handle

/spaces/alice/poc
/spaces/bob/poc

​

Aliases

Aliases are UTF-8 strings with no formatting restrictions. They are optional, user-specified, and can be changed at any time.

Their purpose is to give users full control over how resources are represented in UIs, and they do not uniquely identify resources.

Example of an alias

Thís îs an alïas! かっこいい!