10 Key Principals of Successful API Design

10 Key Principals of Successful API Design

Today a key strategic consideration for forward-looking businesses and public authorities is innovation. The most pervasive driver of innovation is IT. IT innovations are catalysts for innovation in every other domain. Moreover, IT provides us the opportunity to tap into the holy grail of network effects at exceedingly low transaction costs. As such it provides us the leverage to disrupt vertical markets and build ecosystems around our business. Software is eating the world.

As the digital glue of an increasingly connected world API’s are in their turn the great enabler of IT innovation. As Steven Willmott, CEO of 3Scale, points out in this blog post: if software is eating the world than API’s are eating software.

Because of the importance of API’s here are 10 Key API Design Principles. Download the infographic for your archive. These API design principals are based on input from the API Web Design E-book Crafting Interfaces Developers Love, by Brian Mulloy, vice president of Apigee Labs, Licensed under CC BY-SA 3.0. Please find the E-book here.

1. Design from the developer’s perspective
Maybe the most important reason to expose business assets through an API is to tap into the creative power of the masses. In the end it’s the developers, internally and/or externally, that are going to develop the apps your customers (end users) are going to use. Therefore, when building an API your primary design axiom should be to maximize developer success. As mentioned in a previous blog post on API Strategy and the API Value Chain it’s not important what API you create, but what it enables developers to create.

2. Keep it simple
A golden and universal design rule is to keep things simple. This also counts for API design. It should be exceedingly simple for developers to use your API. In this regard a simple and intuitive base URL of your API is fundamental. After all the base URL is the most important design affordance of your API. Keep verbs out your base URL and use HTTP verbs (GET, POST, PUT, DELETE) to operate collections and elements. Remember the words of the pioneering French aviator Antoine de Saint Exupéry’s: “It seems that perfection is reached not when there is nothing left to add, but when there is nothing left to take away”

3. Don’t forget error handling
Typically errors only account for a fraction of all messages sent by the API. However, they are the most scrutinized messages by app developers, because developers simply make errors. To prevent developers abandoning your API it’s important to make it as easy as possible for them to use your API. There are many error handling measures you can consider but in our opinion the most important ones are:

• Use a limited number of common HTTP status codes
• Set Location
• Provide a Help URL
• Use plain – human readable – error messages

4. API’s change, so release versions
If there is one thing true about your API it’s that it will change.
Bugs need to be fixed, security holes closed, out-of-date schemas updated. On the other hand it’s a guarantee for failure if you make such dramatic changes to an API that is already in use that it crashes. By versioning your API you can make changes without breaking already-existing implementations. The latter is the key determinant for whether or not a new version is imperative. You should consider only a new version if the change in funtionality will break current implementations.

5. Support Partial Response
Google introduced partial response in 2010, almost 4 years ago. By supporting partial response only a subset of information can be transferred. Partial reponse is about improving efficiency and eliminating redundancy. Less data transferred over the network means less bandwidth usage, faster server response, less CPU time spent on the server and client side, as well as less memory usage on the client side. You can suport partial response by adding optional fields in a comma delimited list.

6. Support multiple response types
You cannot assume that developers will use only the response type you prefer. Therefore use more than one format and accept as many formats as necessary. Supporting XML, JSON, PHP, and others is not much more work and yet has a measurable impact on your APIs adoption. Use JSON as your default response type.

7. Provide shortcuts or composite responses
APIs should be very simple and easy to use. Ease of use also implies granularity: developers can get exactly the data that they need, not more. The downside of granularity is the ‘chattiness’ of the API. Chatty apps are constantly making data requests and because application processes are often dependent on each other, each call has to wait for the preceding call to return data first. This problem can be mitigated by providing shortcuts or composite responses if needed.

8. Implement the API Façade Pattern
It cannot be said often enough: simplicity is key to API adoption by developers and therefore API success. One measure to improve API adoption is to implement the API Façade Pattern. This is because the back-end of your internal systems of record are often too complex to expose directly to developers. The API Façade Pattern enables you to break down the complexity of your system in ‘digestible’ or less complex subsystems or problems.

9. Build a dedicated API portal
Consolidate all API requests under one API subdomain for the sake of ease of use.

10. Provide a SDK
Complement the API with code samples, libraries and software development kits. The SDK will help to reduce bad or inefficient code and market the API to different developer communities.