How to Create a Great API

"A well-written program is its own Heaven; a poorly-written program is its own Hell." - The Tao of Programming.

The Good™ design, implementation, and use of an API is far from a simple task, and as with so many things related to design, beauty lays within true simplicity, not unmanaged complexity.  Below Darin Kelkhoff and I lay out what are the top 10 requirements for a great API.

1 - The Number One Feature of a Great API: An Extraordinary Support Team

So, you’ve got all the functionality, dexterity, and resources at hand.  But you’ve got an inkling that these aren’t all you’ll need. You need grit, compassion, intuition. It’s the extraordinary people behind a great API that make all the difference. You need to be able to ask questions when you’re legitimately stuck.  You need to talk with someone who can truly understand what you’re aiming for and will give you what you need, not just what you say you want. An extraordinary support team does just that; their goal is your success.

2 - Common Up/Down Objects

This point concurs with #8: internal consistency. An internally consistent API equips you to download an object (i.e., from a GET), modify the fields you need to update, and then send it back to the server (i.e., PUT or PATCH) to update it. Or perhaps it helps you clear out the object ID and send it back (POST) to create a new duplicate record. A robust API with common Up/Down objects gives you that same object, no matter what direction it’s moving.

3 - API Request Log Within the Application

You know you have a strong API when you can log into the system you’re working with and see a full log of all your API requests. This log is valuable both when you’re developing—to see exactly what the remote end is getting—and once you’re live and you’re no longer making those requests yourself. A built-in API log is a huge debugging tool.  

4 - Meaningful Error Codes and Messages

Even the best of us get errors when we’re working with a partner’s API. You remember the old saying: “If at first you don’t succeed, you must be a programmer.” When inevitable errors bounce back from the server, the quality of the error codes or messages is crucial. This quality alone draws the line between hours of debugging or getting it right on the very next try thanks to a simple error message.

5 - Easy, Direct Use as RAW JSON

#6 taught us that API libraries are crucial. On the other hand, if the ONLY way to use an API is through its library, its functionality is compromised. The good news? There are so many great tools out there (Postman, Paw, and the ubiquitous command line with curl). With tools like these, you’ll be able to make ad hoc calls to your API—that’s a huge advantage.

Let’s say you need to see all possible values from a resource. Don’t build it into your app; just drop it into Paw and get an instant result. Or maybe you need to make a one-off call to update a record; five minutes in the shell can save you an application build, deploy, and release cycle.  

6 - Client Libraries for Popular Languages and Frameworks

Ideally, API take-off requires only four steps: 1) download the API’s library; 2) add it to your package manager; 3) import the objects; and 4) go! That’s why having a vendor who provides a primed-and-ready library is crucial. That library allows you to ignore so many questions during implementation: “Is it JSON or XML?” “How are you doing authentication?” “What error codes do you return?” A pre-built library allows you to perform at your highest capacity since these details are already covered.

7 - Consistent Simplicity

As engineers, we tend to fall into the trap of complexity. Writing a complex piece of logic is alluring—you can brag about it to your colleagues. But it’s also a sure-fire way to antagonize your API users. APIs need to be simple to be loved (as simple as they can be while still working at top capacity). Own that challenge, and you’ll succeed as an API designer.

8 - Internal Consistency

The best user guide is the one that you never have to crack open—because you already know what to do, thanks to past experience.  An internally consistent API makes that possible.

In the world of API, internal consistency means that every endpoint exposes the same operations with the same syntax and the same kind of output. In short, one field has the same name on each resource where it’s exposed. You’ll never be surprised at the responses you receive. And you’ll be confident using the full API without scouring the documentation first.

9 - The Ability to Interactively Try it Out Online

You know you have a leading-edge online documentation tool when you can make requests to the API through the documentation page itself. Instead of cycling between reading the page and editing your code to try something new, you can play with the API live, right there on the page. This option drastically shortens cycle-time when you’re testing new changes or resources.  

10 - An Up-to-Date Knowledge Base and Online Documentation with Examples

You’re jumping into a new API, and you need documentation—documentation on how to get started.  You’ll find this in the form of a knowledge base. Ideally, your knowledge base gives example code for common-use cases you are building.  

After you are up and working, you’ll be ready to dig into all the ins and outs of the API.  At this point, you need a full reference that gives all the details, including the resources, methods, and the level of every field.