How To Design A Good API

YourAPIExpert Essential Series

Getting an API ‘just right’ is a skill.  A good API sets apart those who program APIs because they have to from those who program APIs because they want to.

This article is part of the  ‘Essentials’ series and focuses on the ground-level understanding required to undertake the journey in to the world of APIs and will through the course of the series build upon your skills and introduce you to core concepts.  This series is intended for people who wish to gain a rudimentary understanding of APIs such as students, new software developers and managers wishing to gain understanding and experience within their team.

I always advocate that a good API is amongst a corporation’s greatest assets.  If the API is for public use a good API translates to increased customers and long term revenues.  As developers integrate the API in to their products and services so your usage and customer base grows.  If the API is for internal use you can look forward to significant cost savings and operational efficiencies.

The process of getting from the planning stage to the implementation stage is unfortunately mismanaged by many organizations resulting in poor quality and borderline unusable APIs.  A public API is forever.  There is really only once chance to get it right.  Once the API has consumers it becomes an exponentially more difficult task to replace it and correct bad design.

What Makes An API Good?

A number of recurring characteristics are found in good APIs which set them apart from generic run-of-the-mill competitor provided APIs.  To create a market-leading API one should ensure that the following characteristics are present.

An API Must Be Easy To Learn

Once an API is released it requires adoption by developers and integrators.  Without it the API is has no traction, is underused and forgotten.  To make use of the API developers and integrators have to be able to study your API and understand it.  The more difficult this task is the more inclined the developer is to move to another competitor’s API.

This places emphasis on the critical need to properly and intelligently design an API’s Northbound interface so that it makes sense to a developer irrespective of their level of skill or familiarity with the API.

The cornerstone of an API’s ability to be well understood rests upon consistency and predictability.  For example once an organization has standardized on an authentication scheme it takes on a static form in the representation of an API.  There are a number of standard parameters which does not change across APIs and therefore should not change across the document.

Correct Incorrect
userName user / user-name / user_name / username / user name / uname / uName
passWord pass / pass-word / pass_word / password / pass word / pword / pWord
consumerKey key / consumer / consumer-key / ckey / apiKey
secretKey key / secret / secret-key / skey / apiKey

In the example above I have documented a few common parameters used when authenticating to APIs in order to demonstrate how to correctly think about naming conventions.  In the example I have made use of camel case as it has become an industry norm and is used extensively in the design of RESTful APIs.  Another consideration to be aware of is that I did not abbreviate or shorten the parameter name.  Without requiring documentation or extensive learning it is clear to understand the nature and purpose of the parameter name in line with the API’s self-describing nature.  I also did not complicate the parameters with hyphens or underscores.

Therefore in any design of an API a great amount of emphasis must be placed on the naming of the parameters so that they are immediately clear and well understood with the most minimal of description or reasoning required.

An API Must Be Easy To Use

Imagine the consequences if an API was not easy to use.  Quite simply, nobody would use it.  An API’s adoption and the speed of its adoption relies upon its ease of use.

A good API should be easy to use even without its documentation.  If a parameter was named ‘secretKey’ as opposed to ‘skey’ it is immediately understood what is required.  Similarly if the request parameters and response parameters of an API made sense to even the most unskilled of developers the API will take on an air of friendliness which invites use.

Conceptualizing or designing an API without its documentation forces the developer to evaluate the core information they would require to make use of the API as well as how it should be presented for maximum clarity.

An API Must Be Built To Fail

Sounds counter-intuitive does it not?

There exists a great number of things which will cause an API to fail and a good API is able to circumvent or manage these causes either through ideal internal design or through the assistance of external mechanisms.  An API does not have to physically fail to be regarded as a failure and one often overlooked aspect of an API is its interaction with the public.

If there is the lightest likelihood that an API can be misused in any way then it is inherently a failure.  ‘Misuse’ is a broad term but it implies that the API may be used for a purpose other than what was intended either through willful or ignorant acts.  Suffice it to say an API can be misused willfully through denial-of-service attacks, brute force attacks or other forms of negligence or as innocently as a misbehaving script or application from a trusted partner.

Unhandled and unmanaged these acts could have devastating consequences to the API and the systems behind it.  Consequently an API must not only be able to tolerate the common events such as network outages, system outages and security risks but also the propensity for customers to incorrectly make use of the API.

Therefore the API must be built to fail.  It must be designed and constructed in such a way so that failure, whether occurring within itself or is assisted by a customer action is managed and does not result in reduced performance or unavailability of the API for other customers.

An API Must Do One Thing And Do It Well

A fundamental architectural principal of an API is that it must offer reusability.  It is a goal which will never be achieved if a single  API is compounded with too many functions and roles.

I have seen some hideous APIs bloated with functionality which ultimately came at the cost of an API that did not scale well, did not perform well, was difficult to maintain and had reached the limits of its extendibility.  It is no surprise that the development team absolutely loathed APIs.

An API should only do one function and at most a small set of functions and be able to do them extremely well.  An instruction to place an order and an instruction to process billing are two distinctly different instructions.  Similarly an instruction to create an order is different from an instruction to view an order.

In most cases developers will group similar functions in to a single API for the convenience of working with the same Southbound interfaces and is largely dependent on what makes sense.  For example the interfaces to create an order and to query its status may be built in tot he same API and be made available publicly.  Similarly the interfaces to cancel or alter the order may also be built in to the same API but with additional authentication requirements or restrictive permissions.  Ultimately these interfaces would take the form a single and purposeful ordering API.

Affording the API with the correct and appropriate security mechanisms, understandable input and output parameters and descriptive payload responses will yield an effective and usable API.

Next Up:  How Do I Implement A Good API?

Pages: 1 2

Written by YourAPIExpert