Opaque IDs for improved understanding

Photo by Giang Vu on Unsplash

A what ID?

What is an opaque ID? It’s an ID that rather than just being an unique identifier includes information about what the ID represents.

For example, rather than just returning a profile’s ID as 12345, we return it as pro_12345. Similarly for a calendar belonging to that profile, rather than returning 67890 we return cal_12345_67890.

We do this because for a few bytes of overhead we think it makes our API easier to learn. An ID in isolation be it in documentation, in a response, or stored in a database is much more meaningful.

Improved understanding

Opaque IDs make it easier to understand and translate examples to your application. When the example using a cal_ ID, it's obvious you should be providing one of your own cal_ IDs in the same place.

It makes it easier for us to spot errors in support cases as we don’t have to lookup what each ID refers in order to fully understand an example request.

This saves time for us as the provider and for you as the consumer, it’s a win-win situation.

Coupling related values

Composite opaque IDs like cal_12345_67890 also make things simpler for the consumer as rather than providing two pieces of data they pass one. Rather than a URL structure like:

/v1/profiles/{PROFILE_ID}/calendars/{CALENDAR_ID}/events

We have:

/v1/calendars/{CALENDAR_ID}/events

This is because the profile information is embedded within the ID. That simplification again surfaces for more efficient support as it’s much easier to copy and paste one value into a search dialog than two. A customer will always provide a composite ID as one value, whereas if it is two separate pieces of information they may well be spread out in their correspondence.

Overall this approach is a win for everyone involved. We’d heartily recommend using it in your own API design.

Originally published at https://www.cronofy.com on July 19, 2016.