8 Simple Rules for Building Great APIs

APIs or Application Programming Interfaces have already been around for a long time, but when people talk about “APIs” nowadays, they often discuss the very specific software interfaces that expose organisations’ capabilities over a network within or outside these organisations. A well-known example is the public Facebook API, which exposes some of Facebook’s capabilities, like the ability to publish a new status update or a picture on a Facebook page and the ability to retrieve published pictures. Another example is a private or public API that exposes accounting capabilities within or outside an organisation, or an API that exposes a bank’s capabilities to its trusted partners.

Having such APIs is interesting because they can be used as building blocks for various IT solutions such as web applications, mobile applications, system integrations and Internet-of-Things solutions. While these solutions are often built by the organisation owning the APIs, other parties like business partners or consumers can also build them if the APIs expose their capabilities outside the organisation - for free or at a charge. As such, externally exposed APIs can constitute a new business channel that can foster innovative uses of exposed capabilities.

Building APIs, however, is not without challenges. While APIs can be considered strictly technical assets, the best APIs are often built by multidisciplinary teams because there are just so many things to think about. In this blog, I’ll share some simple rules to get you started.

1. KISS: Keep it simple

By exposing simple capabilities that are well-named and documented through simple and clear terminology, you will foster and ease the adoption of the API. Everyone will be able to see what the API can do and HOW to use it without requiring additional help. Of course, the API should not only be clear to the team that builds it, but also and most importantly, to the target users. Simple APIs have the additional advantages that they can hardly hide design issues and might have less bugs since their functionalities are more clearly stated.

2. Use consistent terminology

Inconsistently naming or documenting the elements within APIs leads to frustration and possibly bugs for your users. If, on the other hand, your APIs are fully specified using consistent terminology, they will become a consistent whole that is easy to understand, easy to use and predictable!

3. No unexpected side-effects

When API capabilities start doing things they should not be doing, like debiting a credit card whenever the preferred shipping method for a web shop account is changed (whoops, forgot to document that!), the API users will quite likely get confused and annoyed. Unexpected side-effects must be avoided, or, in other words: documentation should be complete.

4. Offer focused capabilites at the appropriate level of granularity

To maximize usability, each capability should have a clear focus and an appropriate level of granularity. While capabilities that are too fine-grained can be difficult to use, and might require very chatty API interactions to realise a use case, capabilities that are too coarse-grained might be usable only for one specific use case. Hence, to facilitate anticipated uses while also making innovative, possibly unanticipated uses possible, it’s a good practice to expose coarser-grained capabilities that directly support particular use cases together with any useful finer-grained capabilities. Internally, the coarser-grained capabilities can, for instance, delegate to some finer-grained ones to realise their functionality.

5. Offer additional flexibility

If you’re expecting a wide variety of users, it’s interesting to make your API sufficiently flexible to meet the various user groups’ requirements. For instance, you can support multiple data languages (e.g., English, Dutch, French …), data formats (e.g., JSON, XML, HTML, RDF ...), security mechanisms (e.g., for authentication, encryption …), API technologies (e.g., SOAP, REST or other protocols, or even client libraries for JavaScript, Java, Ruby …) and so on.

6. Keep performance in mind

Great APIs must perform well, especially if they support use cases that require prompt results like functionality in online user interfaces. Hence, performance is an aspect that should be constantly considered. For instance, during API design, input and output payloads should be optimized to not be unnecessarily large. I/O is computationally expensive and can easily slow things down (a lot). During realisation, on the other hand, the APIs’ performance should be optimized through the appropriate implementation- and deployment techniques, and be tested in a realistic setting: using system resources similar to the ones in the production environment and with similarly realistic network connectivity between the test clients and the API. Mind the use of multiple test clients: APIs will typically be accessed concurrently and should be tested accordingly! Next to minimal latency, availability is also important: you probably want to protect your API from abusive uses/attacks (more about that in rule #7) and have procedures ready to quickly recover from any failures. Finally, the service levels that can be expected should be clearly documented for your API’s users.

7. Leverage API Management

An API Management solution is a valuable component for realising APIs so it’s strongly advised to at least consider using one. Amongst others, an API Management solution can augment APIs with security (e.g. user authentication, authorization, communication encryption), throttling, quota, caching and routing mechanisms. Furthermore, it may also support monitoring and have reporting and alerting features that can be useful to detect API misuse or abuse, but also unanticipated API uses that can be interesting for future API design (i.e., to be better supported in the future). Some API Management solutions also come with a Developer Portal to support the developers that will build and use the APIs (e.g., by offering them discussion forums, API user registration, usage examples, terms of use and pricing details).

8. Track some pilot users

As an alternative or complement to monitoring, observing and closely supporting pilot users for your API can provide valuable feedback that will guide you in your API design. Furthermore, their experiences and use cases can be documented as interesting case studies for your API.

While these rules will already help you get a long way, there are still some other aspects to consider when building APIs - like how to deal with API evolution - that weren’t covered here because they would simply lead us too far. If you do want to learn more about this topic or have any questions, don’t hesitate to reach out!

Wouter Amerijckx