At Cronofy we expose opaque IDs from our API, a strategy we gratuitously copied from Stripe. So what is an opaque ID?
At Cronofy we expose opaque IDs from our API, a strategy we gratuitously copied from Stripe.
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.
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.
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.
Every six months Cronofy organises a companywide meet up. This May, we met in Amsterdam to give our teams the chance to see our recently opened office and the sights this wonderful European capital has to offer.
Developing how your company describes and represents itself is a challenging and enlightening journey. You have to revisit long held assumptions and confront the reality of what your customers and the market value. I absolutely believe that you can only do this effectively with outside help.