Public API Design Considerations

A recent pre-screen questionnaire asked the following:

For a public API, give order of importance of the following, and reasoning why:

  • Security
  • Data Integrity
  • Scalability
  • Usability/DX

All of these considerations are important when designing and implementing a public API, but the order of importance is somewhat dependent on the kind of data they are abstracting and the policies of the organization whose data they provide access to. For example, an API for an open wiki might not be very concerned with security, but scalability would be important if it were popular. An API for classified information would almost certainly have security at the top, while usability might not be of great concern. In general, though, I would rank these items in the following order:

Usability/DX

Data Integrity

Scalability

Security

My reasoning follows. I will start from the bottom and go up.

It may seem surprising that I put security on the bottom of the list. This is not because security is unimportant. I placed it here because its importance is quite dependent on the nature of the data and the organization. Highly sensitive information would require high security and move this item above all others, while public information might not require any security at all for a read-only API. In some organizations, authentication might be very important, but authorization controls not so critical as long as the API had a good audit trail. An API that allows write access to business-critical data or read access to data that could harm the organization if exposed would certainly need to have strong security as the top priority. Because the level of security is so dependent on the data, I have placed it below other priorities with the caveat that it could move up to the top spot in many situations.

Like security, scalability is also somewhat dependent on the data and what it will be used for. Also like security, scalability could take the top spot in certain situations. An API created for a very specific purpose that would never have many consumers would not need to be very scalable, while an API for a new service that will likely become popular needs to be designed with scalability in mind from the get-go. In practice, its always good to at least consider scalability in API design if not build it in from the beginning. The old adage, “design big and implement small” applies here. Unless you know you’ll never have many consumers (and how can you know this, really?) you should at least design your APIs in a way that lends itself to being made scalable later, even if that scalability is not implemented in the first version.

Data integrity is always important because, if you can’t trust that you can get the same data back out of an API that you put in, what good is it? Good practice would be to validate data on the way in and again on the way out. Ideally, cryptographic hashes or other methods of change detection would be used as well. Ensuring data integrity in an API can also allow consumers to be simpler and better performing because they do not need to handle as much data validation themselves. Data integrity would be the most important concern of any API if they didn’t have to be understood by humans.

I have put Usability/DX on top because, for an API, the developer is the customer and the customer experience is the key factor in the success of any enterprise. If an API suffers from poor usability, few will use it (unless they have no other option) and those that do are likely to use it incorrectly. An API is a contract and incorrect use it due to misunderstanding is a violation of contract that could have disastrous results. APIs make it easy to change or destroy a lot of information very quickly. If the developer of an API consumer has difficulty understanding the API, they are likely to make mistakes in implementation that could be potentially catastrophic without either the developer or the end user having any ill intent. In my experience, these types of misunderstandings are far more dangerous than disk failures or even nefarious hackers.

Finally, I would like to note that these areas are all interrelated, with each one affecting the others. For example, a complex security scheme might reduce usability and could make scalability more complex, while poor security could allow users to bypass or disable validation and affect data integrity. The order of importance is somewhat fluid, would have to be evaluated on a case-by-case basis, and be re-evaluated over time, but certainly none of these areas are unimportant.

Leave a Reply

Your email address will not be published. Required fields are marked *