5 Design Qualities for APIs

Here are some API design qualities mentioned by Jaroslav Tulach1.


The API should be easy for the users to understand.

  • Have a persona of the user. Understand what skills they generally have, what knowledge about general knowledge about the domain they are already familiar with. The persona profile should answer the question: what concepts do we expect the users to already know ?
  • Prefer using concepts the users are familiar with (common knowledge) to reduce the learning curve. Only use new concepts if you have to.


Preferably, there should be one consistent way to do things across the API. For example, if the way to make an idempotent call is to use and idempotency key, then that should be the model used consistently across the API for idempotent calls.


Make API endpoints and operations easy to find, understand and use. This starts by having a clear understanding of the job the user is trying to fulfil. Provide entry points and guidance. Group related functionality together so they are easy to find. API should provide operations that are relevant to a particular user audience, and the jobs they are trying to perform. Mixing operations for different user audiences into one API hurts discoverability. This is because it makes it more difficult for the audience to know if they should care about a particular operation or not.

Simple tasks should be easy

We should optimize the API for the job the target audience is trying to perform. Optimize it to make simple things easy. Having multiple audiences for an API makes it difficult to understand and optimize for the target audience.

Preservation of Investment

When users integrate with an API, they have invested their time, study, energy and money into it. We need to preserve this investment of our API users. Each new API release of the software should not break existing APIs, or where that is inevitable, should provide easy upgrade paths.


  1. Practical API Design: Confessions of a Java Framework Architect by Jaroslav Tulach

Leave a Reply