6 Resource identification

In this chapter, we’ll explore resource identifiers in-depth. This includes what they are, what makes for a good one (and a bad one), as well as how they can be used in your APIs. We’ll also dig in to some of the common identifier formats in use today (such as universally unique identifiers or UUIDs; https://tools.ietf.org/html/ rfc4122), as well as new custom formats targeted specifically for use in web APIs.

6.1 What is an identifier?

First, what exactly do we mean when we talk about resource identifiers? In short, identifiers give us a way to uniquely address and talk about individual resources in an API. In more technical terms, these identifiers are chunks of bytes (usually a string value or an integer number) that we can use as the way we point to exactly one resource in a resource collection. Almost always, these identifiers enable users of an API to perform some type of lookup operation. In other words, these identifiers are used to address a single resource among some larger collection of resources.

6.2 What makes a good identifier?

6.2.1 Easy to use

6.2.2 Unique

6.2.3 Permanent

6.2.4 Fast and easy to generate

6.2.5 Unpredictable

6.2.6 Readable, shareable, and verifiable

6.2.7 Informationally dense

6.3 What does a good identifier look like?

6.3.1 Data type

6.3.2 Character set

6.3.3 Identifier format

6.3.4 Checksums