APIs have become very important in a world of interconnected applications. APIs have improved a lot in the past years, especially due to the JSON + REST standards. But there's still a more subtle lesson to be learned about them that is a hit and miss: APIs are user interfaces too.
It's in the acronym: Application Programmable Interface. Interface for what? For other software systems. But who writes those systems? Developers. So it's really a user interface for developers who work with your application. Since APIs are user interfaces, we should apply UX principles and techniques to make them easier to use. Here are 5 of them.
The best way to do this is by providing ready to use code samples for most common programming languages. At the time of this writing, you should provide at least code samples for Java, C#, Javascript, ruby, python, PHP. These code samples should provide enough information to connect to your API, authenticate and implement the most common scenarios. More about that in topic 4.
For extra friendliness, if the user is logged in, show it in the sample, the code with the logged in user's authentication token, so that it's ready to use. That is, instead of:
client.call(<YOUR_TOKEN>);show
client.call("ASFasfduoiw2343vc");The best APIs to use are very easy to learn. Writing a lot of documentation is not enough. Your users don't have time to search through hundreds of pages of manuals, they're on a deadline. So could they deduce instead what to do for a scenario they've never tried before?
Many APIs show that they can. The key is consistency. The highrise [API](https://github.com/basecamp/highrise-api( is a great example of consistency. Highrise is a simple but very useful CRM SaaS. It provides consistency on many levels:
REST access to all resources
Similar response structure for requests to similar resources
Consistent naming of fields in the response
Both XML and JSON response, controlled by user
Once you learn how to use one resource in the highrise API, the others come natural. Want a list of people?
GET /people.xml
<people>
<person>
...
</person>
<person>
...
</person>
</people>
Want a list of companies?
GET /companies.xml
<companies>
<company>
...
</company>
<company>
...
</company>
</companies>The response for both companies and people contains fields for contact information, structured exactly in the same way:
<contact-data>
<email-addresses>
<email-address>
<id type="integer">1
</id>
<address>
corporate@example.com
</address>
<location>Work</location>
</email-address>
</email-addresses>
<phone-numbers>
<phone-number>
<id type="integer">2</id>
<number>555-555-5555</number>
<location>Work</location>
</phone-number>
<phone-number>
<id type="integer">3</id>
<number>555-666-6667</number>
<location>Fax</location>
</phone-number>
</phone-numbers>
</contact-data>The highrise API is a very interesting case study in learnability and consistency, and we invite the readers to try it and to get inspiration from its design.
One of the most annoying things that happens to developers is when they manage to write code that is supposed to work and yet it doesn't for some strange reason. When working with APIs, this is especially annoying. Typically, the developer has only two ways to figure out the problem: search through documentation or ask the support. Each of these makes users waste precious time. Good APIs have consistent behaviors. They return the same error code for the same error. They treat as many errors as possible. They provide a helpful message to the developer to understand what is wrong and how to fix it. And, for stranger situations, they provide an easily searchable reference of problems with solutions. Plus, they provide fast and helpful support when needed. There are also ways to avoid most of these problems: design the API such that it's very hard to make mistakes. If many users make the same mistake, improve the design such that it doesn't happen. Not only wills this increase user satisfaction, it will also reduce support work. Everybody wins.
Since APIs are user interfaces, you should understand the user scenarios and test them with usability tests. Let's take a CRM like highrise as an example. Common scenarios might include:
Get a list of all contacts for specific criteria to do something with them (eg. create invoices)
Create a report of deals for a specific period of time (eg. 3 months report of total, won, pending and lost deals or the average lead time from creating a deal until won or lost)
These scenarios can in turn be broken into smaller steps, resulting into simple implementation steps. Each of these steps can be tested by:
Implementing a API (if you're just starting, it can be a dummy implementation)
Asking developerss who've never used it to do one of those steps or a more complete scenario
This information is in turn used to simplify and improve the API design.
There are two ways to develop an API:
bottom-up: we implement an API, release it and see if it works
We recommend the top-down method for best results. Instead of making assumptions about the API, start from the point of view of the user. Write the code that you'd like to write in order to use the API 2 and once you're happy with that, start implementing the API. The usage code can then serve as functional tests for your API and as code samples for the documentation. It's a win on all fronts.
Here it is: 5 tips to create a great user experience for a developer who uses your API. Each of these tips is inspired by at least one of the five usability principles: learnability, efficiency, memorability, avoiding mistakes, satisfaction. In the age of SaaS and mobile applications, the teams who do that brilliantly will be noticed. Good luck!
PS: Don't forget to contact the authors if you have any comments, questions or if you disagree with the article. Thank you!
This technique is called "programming by wishful thinking".
by Lőrinc Pap
by Ovidiu Mățan
