Application Programming Interfaces (API) are now present in most websites and mobile applications. They were developed to help deliver services online, and evolved into simple, customizable digital services, which can be easily adapted to work for a wide range of third party web and mobile apps.
The core principle of a good API is ergonomics. We are talking about user-centric design, where every element and every function serves a purpose necessary to the user, in the simplest and most straightforward manner.
User Empathy—the Basic Principle for API Design
Each of the guidelines that will be presented below has one simple principle at its core: empathy with the end users of the API, that is, the developers. Once API creators understand the need to provide developers with robust and versatile tools to include in their projects, the guidelines below will become not just common sense, but also a second nature when building a new API.
At the same time, it must be noted that some of these guidelines are not specific to API design. Some of them are derived from user interface design guidelines developed back in 1995 by Jakob Nielsen. This means one thing: good design principles are more powerful and valuable than the most exciting trends. A trend will promote certain products and keep them popular for a short while. Solid usability principles help create evergreen digital properties that will never become obsolete.
Leaving theory aside, these are some of the best guidelines for improving API design:
1. Focus on Building a Granular API
A granular API is an API with the lowest degree of specialization. It means that it performs a simple action which can be modified, extrapolated and customized to adapt to a large variety of projects and specifications.
Think generic stock vector image versus custom made design. A great API is the generic stock vector image that can be resized, reshaped, undergo color palette changes to fit a specific design.
2. Manage API Versioning Adequately
Setting the correct version of API will help developers work with a specific API even after major updates and upgrades. Lack of versioning may generate errors and unsupported requests when these are directed towards modules belonging to an older version of the API.
Creating backward compatibility through versioning will allow a developer to streamline the transition from the older version to the new one, without losing functionalities and availability within their own web or mobile app.
3. Strive for Error Prevention within the API
Designing error messages that help the user understand and solve the problem is good. Making sure that an API is as error-proof as possible is even better. The testing phase before releasing an API is as crucial as the development work itself.
Some of the most important aspects to check and review are:
- Whether documented examples of errors are incorrect or misleading
- Whether the API malfunctions easily when changes are applied to the interface
- Whether the API design is too complex and may cause undocumented and unexpected errors.
4. Apply Generally Accepted Industry Standards
API creators must strive to make their work as usable as possible for a wide range of web and mobile applications. This means that an API should not incorporate new and untested technology standards. The API creator should keep in mind these two important factors:
- The best technological solution is the one that requires the least effort to implement into a project
- No assumptions should be made on the software development technologies used in creating digital products which will incorporate the API.
5. Enable Auto-Loading of Relevant Resources
APIs should be small in size and have good performance—thus they can access third party resources which are needed for proper functioning but are not incorporated into them. However, if the end user has to wait during every session until these resources are accessed and loaded, the usability of the API is reduced and does not meet the requirements of a streamlined process.
A simple solution to solve this problem is adding instructions in the API for the auto-loading of critical resources, so that the function works in a seamless manner at all times.