Evaluating or developing an API? Here’s our list of essential elements to consider…

I’ve been designing and consuming APIs in one form or another for well over 20 years, and along the way I’ve had plenty of opportunities to see the good, the bad, and the downright ugly. In particular, the essential elements of a great API that’s both a delight to use, as well as to maintain.
As the LibLynx Connect API lies at the heart of our service, getting it right is critical. As an aide-mémoire, I’ve distilled my experiences down to the acronym FLIES:

So if you too want an API that FLIES, read on!

F Fit external use cases, not internal ones

The frameworks many current applications are developed with can make it easy to expose internal data structures to an API. But often, these structures are the result of design decisions that have no bearing on how a 3rd party will use that data. This is designing from the inside, out. It forces the developers using your API to jump through additional hoops.
A better way is to design from the outside, in.
Consider what the perfect API would look like from a 3rd party perspective. Then build adapters between that perfect world and your internal compromises. If it sounds like extra work, consider that adapters will also help to insulate your API from internal changes. Everybody wins!

L Learnable by different types of user

Good documentation is usually identified as a key goal for any API. But what makes documentation “good”? We approached this as asking ourselves what kinds of people needed documentation, and how could we support different learning styles?
A popular model for the different types of learning is VARK, which comprises these four types:

Type Description What to include?
Visual use of diagrams and visual aids Explanatory high level diagrams – how does information flow through the API to support a 3rd party application?
Auditory primarily listening but also speaking about a new topic Video-based tutorials and walkthroughs to support those with an auditory preference
Read/Write learning from written information Clear and searchable documentation which cross reference “how to” guides with reference material
Kinesthetic learning by doing A playground or sandbox that allows API requests to be made without writing any code

Don’t underestimate how useful an interactive sandbox can be. Our technical manual includes a sandbox, but we also added a guided tutorial that walks through a typical set of API interactions, allowing you to tweak the inputs and observe the effect on the response. It proved to be useful not only for self-guided learning, but also as a visual aid when speaking to developers.

I Intuitive and human readable

While the previous point is focused on the documentation, we think it’s important to make the system as self-documenting as possible.
It’s easy to make data a computer can read. The real trick is to make sure humans can read it too. This doesn’t just help during the initial exploration and evaluation of an API – it makes debugging and diagnosing problems much easier too.
We primarily use JSON with ‘snake_case’ naming convention, favouring descriptive names for variables over short, cryptic ones. We wanted objects to be as self-descriptive as possible to eliminate the need to constantly refer back to a technical manual.

E Edible – eat your own dogfood!

“Eating your own dogfood”, a colourful phrase popularized by Microsoft, refers to the practice of a company using their own products.
It’s a very powerful way of ensuring an API is useful for real world tasks.
It’s a lesson we learned early on. As we built our first authorization API, we used it to provide authorization services for its own technical manual. This allowed us to experience using the API before any of our customers.

S Standards used where possible

Using standards can help to lower the barriers to using an API. Using JSON for data transfers and OAuth2.0 for authentication are no-brainers, given such wide support for them.
REST, while not a standard per se, is more than just “clean API URLs”. It’s well worth reading Roy Fielding’s original paper covering REST. From those foundations, the Richardson Maturity Model is also a great way to appreciate the fundamentals of RESTful design.
Also, a good understanding of HTTP is essential to making an effective REST API. For example, caching and compression headers can make a huge difference in efficiency.
Even where there are no de-facto standards, try to avoid inventing new things. We wanted to include links in our JSON objects, and rather than create our own format for them, we adopted HAL.
Feel free to contact me if you’ve got any questions or feedback about our API – we welcome input.
Paul Dixon
CTO, LibLynx LLC

Credits

Image adapted from fly by Helga Birna Jónasdóttir (used and adapted under cc-by-2.0 license)