Best Practices for API Design

If your API is insufficient or non-existent then your application data and metadata will become part of your de-facto API. You don’t want that. . . really.


Here are some points to consider when designing an API or SDK:


  1. Get to know your users. Remember that you are an expert, but you are designing for non-experts. The goal is to make things easy for the user, not to impress them with how smart you are. Simple is king except when it violates the principle of least astonishment.
  2. Get to know your users. Write applications like those your users will create. What do you need from an API in order to implement these applications? Once your API is released, ask for copies of applications your users have created. 
  3. Make common things easy and unusual things possible, but do not allow users to do evil things. Verify preconditions and inputs.
  4. Design for subclassing or prevent it.
  5. Accessor methods, not direct access to data, and Factories, not Constructors.
  6. Define, test, and measure usability.
  7. Get to know your users.


Some References: 

Leave a Reply