Stripe engineers explain the benefits of making IDs human-readable for use in APIs

Paul Ages, an engineer at payment service company Stripe, wrote a blog post explaining why Stripe's object IDs are human-readable.

Designing APIs for humans: Object IDs - DEV Community

https://dev.to/stripe/designing-apis-for-humans-object-ids-3o5a

Every business needs a database to store important data like customer information, order status, etc. To uniquely identify data and quickly retrieve stored data, databases need to have IDs, also known as primary keys.

The simplest approach to IDs is to assign consecutive numbers, which seems like a good idea because it is easy to set up and use, but it has security issues because a malicious attacker can guess other IDs.

One possible ID candidate is a UUID, which is a random 32-digit alphanumeric string such as '4c4a82ed-a3e1-4c56-aa0a-26962ddd0425.' It is considered one of the best methods because it has many advantages, such as being quick to generate, having a proven track record, and having almost no collisions.

On the other hand, Stripe uses IDs in the format of 'pi_3LKQhvGUcADgqoEM3bh6pslE'. All IDs have a prefix like 'pi_' at the beginning, followed by a randomly generated string. The advantage of this is that you can instantly determine what the ID is by the prefix, such as 'PaymentIntent object' in the case of 'pi_'.

When creating a PaymentIntent, you enter the IDs of the Customer and PaymentMethod objects, and these IDs are prefixed with 'cus_' and 'pm_' so that you can quickly distinguish between multiple IDs.

Another benefit of prefixes is that they allow you to immediately notice if you are using the wrong ID. In the example below, the ID prefix should be 'acct_' because the Account object should be specified, but 'cus_' is specified instead. Without prefixes, it would be much harder to notice such a mistake.

Another benefit is that it helps maintain API compatibility. In Stripe, in order to maintain compatibility with previous versions, when specifying the payment method in PaymentIntent, you can specify the ID of the card object in addition to the 'pm_○○' format ID, which is the PaymentMethod ID.

The presence of the prefix allows the system to instantly determine what the ID is and send a query to the appropriate database.

Without the prefix, it would be necessary to set additional parameters like 'type', which would complicate the API. Whenever you use an ID, you need to include data about which object the ID is, so embedding it in the ID string is a good solution.

Another advantage of the prefix is that the type of ID can be determined from the first few characters, making it possible to set up Discord servers to block confidential information. The ID starting with 'sk_live_' is Stripe's private key, and by setting it up as shown below to block text containing the private key, it is possible to prevent the private key from being leaked due to human error by the user.

Since the private key for production is 'sk_live' and the private key for test is 'sk_test', it is possible to write code that prevents production data from being used in the test environment.

There are other formats for human-readable IDs, such as the IETF's Uniform Resource Name (URN) . Although the method for generating Stripe IDs was not disclosed, a library for Ruby called ' Prefixed IDs ' was introduced for generating such prefixed IDs.