The easiest is to evaluate the design based on a set of guidelines. Nielsen’s “heuristic evaluation” guidelines describe 10 properties an expert can use to check any design (http://www. nngroup.com/articles/ten-usabilityheuristics/) that apply equally well to APIs as to regular user interfaces. Here’s my mappings of the guidelines to API designs with a general example of how each can be applied.

Heuristic evaluation

1. Visibility of system status

It should be easy for the API user to check the state, and mismatches between the state and operations should provide appropriate feedback. An example would be login API. API should provide easy means to check if the use has been logged in or not. Likewise if you try to login again, the API should provide response that user is already logged in.

2. Match between system and real world

Names given to endpoints and parameters should match the API users’ expectations. If you have a GUI matching the API service, you should use the exact same terms in both. Todoist is a good example of this.

3. User control and freedom

API users should be able to abort or reset operations and easily get the situation back to a normal state. If your API provides analytics service or something else that takes time to calculate or process, your API should have abort function too. Purchase process is a good example as well. It consists of multiple steps (often that process is though handled in the backend by multiple APIS). Stopping the process and clearing the basket should be available. Likewise if the order has already been pushed forward, there should be a method to revert/cancel the operation.

4. Consistency and standards

All parts of the design should be consistent throughout the API, as discussed earlier. Developers use a lot of APIs and tools. That’s where they get familiar with standards. Soon they start to expect things to be according to standards. Reasons are simple. Following standards makes tools development easier, it generates predictability (faster to develop with less errors). Standards are global level and should be applied to all APIs.

Http status codes is a good example of standard. You are expected to use them accordingly. You can and some API providers extend the status codes for their own purposes, but still they use the standard ones too (probably not all).

Consistency is a bit different thing although often overlapping with standards. If you choose to do something your own way (for a good reason), then apply that same rule around your APIs. Be consistant in what you do and again you increase the predictability and lower the learning curve in the long run.

For example there is no universal standard should you apply camel case, snake case or kebab case in parameter naming. You need to pick one and stick with it. If you dig the internet around the topic, you’ll find good reasons to pick any of them.

5. Error prevention

The API should guide the user into using the API correctly, including having defaults that do the right thing. I wrote about this couple of days ago “#88 - A good API is not just easy to use but also hard to misuse”

6. Recognition rather than recall

Minimize the user’s memory load by making objects, actions, and options visible. The user should not have to remember information from one part of the dialogue to another.

If the developer is using some IDE, this is easier to achieve. A favorite tool of API users to explore an API is the autocomplete popup from the integrated development environment (IDE), so one requirement is to make the names clear and understandable, enabling users to recognize which element they want.

One of the popular tools for this purpose is Postman. It can read the API spec and provide easy to absorp graphical presentation of the options. In addition, developer can save own API calls in the tool easily.

7. Flexibility and efficiency of use

Users should be able to accomplish their tasks with the API efficiently. If the API is cumbersome to perform the tasks it is intended for, your design is shitty. You should always write code against the API before launching it. That way you will actually use the API and find out possible usability issues and inefficient practices.

For example it might seem logical in one endpoint to do one thing and another thing with different endpoint. But when you actually use the API, you’ll find out that is real use the two endpoints should be combined to make the API for efficient to use. Of course this bundling might kill some of the flexibility, but that is something you need to solve by experimenting, asking from prospect customers and analyse the actual use of the API after the launch.

8. Aesthetic and minimalist design

It might seem obvious that a smaller and less-complex API is likely to be more usable. Offering a massive API with 121 endpoints might not always be the best option. Also forcing API consumers to fill in loads of parameters, makes the endpoints pain in the ass to use. Putting defaults to mandatory fields when ever that makes sense, simplifies the usage of the API even though the design might be a bit complex.

Massive APIs with lots of endpoints should be broken into separate APIs. With the popularity of microservices it seems that we are suffering the opposite. The APIs are broken to “too small” collections. Then the developer must seek needed capabilities from multiple APIs and in worst case the doumentations are in separate locations. That is frustrating. Combining endpoints from multiple microservices at the surface (API management layer) is one way to tackle this issue.

Or then provide libraries to consume the service more easily without having to learn 15 endpoints and all the options to perform needed operation.

9. Help users recognize, diagnose, and recover from errors

A surprising number of APIs supply unhelpful error information or even none at all when something goes wrong, thus decreasing usability and also possibly affecting correctness and security. Error handling is one of the much debated topics among API practitioners. Many agree that error messages should be helpful and you should use http status codes juiced with description and possibly a link to more information.

Error codes have an implied value in the way that they both clarify the situation, and communicate the intended functionality. Consider for instance an error code such as “401 Unauthorized – Please Pass Token.” In such a response, you understand the point of failure, specifically that the user is unauthorized. Additionally, however, you discover the intended functionality — the API requires a token, and that token must be passed as part of the request in order to gain authorization.

Here the link to authentication practices of your platform would give the needed additional details like how the token is acquired, what is the format/length, how long it is valid and so on.

RFC 7807 provides a standard format for returning problem details from HTTP APIs. In particular, it specifies the following:

The advantages of using this can be a unification of the interfaces, making the APIs easier to build, test and maintain. Also if you have unified error message format, your API consumers will appreciate it. Even if you don’t follow the RFC 7807 but have simpler own format like below, just be consistent.

{
  "error" : {
    "status" : 502,
    "message" : "Bad gateway."
  }
}

10. Help and documentation

A key complaint about API usability is inadequate documentation. It’s no wonder that lately API providers have woken up to the crucial role of documentation. The level of API docs has increased and the tools to generate and update documentation even fully automatically has increased. The prominent role of OpenAPI spec with REST APIs has increased the speed of tools development.

Even if you write the most perfect documentation, your customers will need some additional help. Provide means to contact you and make sure that technical people are answering technical support requests. For partner APIs it is found usefull to provide developer support when partner starts to use your APIs. Getting partner onboard in a week and using your developer resources is that is better for business than letting the partner sweat and discover everything themselves and use 1-3 months in the process.

Other items to evaluate

The above is “just” heuristic analysis framework. It’s mostly about design but includes the documentation as well. That is not enough when evaluating an API.

1. Does it solve the problem?

This is actually the question to start from. If the API at hand does not solve your problem but instead creates new problems or unncessary complexity in the app, then it might just be a good idea to look for alternative.

Your developers should know what is the problem and what is needed to solve it. If the features in the API matches the needs, then you have a strong candidate API.

2. Costs

If the API is commercial, use of it will cost you something eventually. Your API should have freemium plan to offer costless learning and testing. After you take the API in heavier use, you probably need to change the plan. You should calculate what are the costs of using this API and compare it with other similar APIs. You should have some rough estimate how much your app will use the API or otherwise you are committing blindly to something that might kill the ROI of your app.

3. Quality as a service

SLA is what interests users since it gives the minimal level of service quality you can expect. Most commonly you will not find this information in machine readable format, but you need to find the document from the service provider’s site.

You want to see statistics as well. Otherwise you are taking just promises. You need to see statistics like uptime and response time. More commonly companies (at least the bigger ones) provide status page either build in-house or with help of 3rd party service like statuspage.io.

An example screenshot from Intercom status page:

Keep in mind that status pages are used in evaluation, but also during use. When ever there seems to be problems, developers seek for status page of your service. In those cases simple trafic lights is often enough to indicate whether your API is causing the issues or not.

You also want to know how many concurrent operations it can handle per minutes/second. Eg what is the performace capabilities limit. Also be sure tho check that is the limit for all the API requests or per customer.

From the stats you be able to see if the performance is enough for your purposes. If it’s lower than needed you need to look for an alternative or build some extra code at your end to bypass the problems arising from the limitations.

4. What others say?

What to other consumers of the API say? What about them who decided not to choose this API? Why did they make such a decision? Developers trust peers very deeply. It might be a good idea to look for comments about the API usage in Stack Overflow and around the web. Contacting existing customers of the API is something to consider as well.

5. Risks

What is the company or organisation behind this API? Can I trust that it exists after 6 months? What is the credibility and credibility of the maintaining organisation? What is the history of this API? Was it launched last week? Do they provide roadmap about the future development? Can we suggest features?

Anyway, it’s always a good idea to make a plan B for the features you are planning to use from 3rd party API. Sometimes that’s easy, sometimes a bit harder. Keep in mind that MrMurphy probably hits you when ever you least expect it. He might manifest in the format of 2-3 APIs failing over the weekend and by so paralysng yout paid service. Bad for business. Evalaluate the risks always.

Some more to read from 100 Days DX