Author: Garry Shutler
19th July 2016
At Cronofy we expose opaque IDs from our API, a strategy we gratuitously copied from Stripe.
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
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.
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:
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.
Hopefully this is an interesting peek behind the decisions we’ve made at Cronofy. If you have any questions about our API or suggestions about how we can improve it, please get in touch with us via email@example.com.
Date: 19th July 2016 | Category: Developers