API Checklist. Things to Consider When Creating an API

25 July 2017 |

api-checklist

Looking back on the early days of Application Programming Interface, the deal was only in deploying and consuming. But nowadays, API universe is expanding day by day offering new approaches and tools to provide various services with API design in the center.

It can be defined as everything that goes into architecture planning, designing, testing and finally releasing. Principally, from a technical sense, your API design is a definition of endpoints, various methods and fields, presented in a JSON or XML blueprint. But, on the other hand, it appears to be a masterpiece that possesses mysterious tech beauty while delivering values to the end-users.

Meaningful API creation can save you from doing a lot of mistakes on the current road. Moreover, have you ever wonder that when you create a new Web API, you build it on the top of some complex system. It might be associated with the chain - when one production overlaps the previous one.

We can go on listing all components but it’s probably going to be too much information and we don’t pursue a goal to remember them all. What is more important, is to make up so-called a checklist with a bunch of things every API should have while designing, testing and releasing to make it a valuable product.

HTTP

#1. Authentication - identify and authenticate the user who accesses the API. HTTP provides the Authorization for this purpose.

#2. Idempotent methods - GET, POST, HEAD, PUT, DELETE, OPTIONS and TRACE are all considered to be idempotent operations.

#3. 4xx vs 5xx status codes - It’s worth mentioning a distinction between these two status codes. 4xx codes indicates a client-side error and 5xx - server-side error.  Thus, the proper usage of these codes classes will help developers understand if something is broken or they did something wrong.

#4. 200 OK - is a response code that indicates that the request was processed successfully.

#5. 202 Accepted - is a response code which indicates that the request is valid but hasn’t been completed. Typically, it is used when a processing queue takes place on the server side.

#6. HTTP Compression — it can be used both for response and request bodies to improve the network performance of an HTTP API.

#7. HTTP Caching — It’s necessary to provide a Cache-Control general-header on the API responses. In case they are not cacheable, “Cache-Control: no-cache” ensures proxies and browsers understand that. And if they are cacheable, you have to take into consideration whether the cache can be shared by a proxy.

#8. Link Response Header — When consider RESTful API, there is often a necessity to provide links to other resources (a json or image). So, when the content-type of the API response doesn’t give a possibility to establish it, Link Response Header specifies method to make this a reality.

#9. Canonical URLs — defines a consistent method for resources with multiple URLs to provide a canonical URL link.

API Design

#1. Content Negotiation - support multiple representations of the resources with the possibility to redirect to specific formats (e.g format=json).

#2. API Versioning - put the version of your API in the URL (e. g. example.api.com /v1.0/ path) to have a safety net in case the API doesn’t work out like you expected.

#3. Bulk Operations - it would be better if clients could issue fewer requests to modify more data. For this purpose it’s necessary to build the bulk operations into your API.

#4. Error Logging — Make sure you design error logging correctly. Don’t use the practice to throw it together. Distinguish errors caused on the client’s side, and errors caused by your software. Put these into two separate logs.

Content

#1. Content Types -  A lot of talks could be said about content types, however, only one thing is worth pointing out - they are important. Atom, Collection+JSON,JSON HAL, or XHTML - all appear to be content types. But the process of defining the own one requires more efforts than you expect.

#2. Date/time — While providing date/time values in your API, use a format that includes the timezone information.

Security

#1. SSL - HTTPS is growing in popularity, nowadays, allowing sensitive information to be transmitted securely.

Other Stuff

#1. Documentation - Include some runnable code in your documentation to get developers up-to-speed as quickly as possible. You can also use some tools like Swagger to provide interactive docs.

#2. Feedback - Provide your API users with a possibility to give a feedback. You may establish it through your support department, or maybe a mailing list.

#3. Automated Testing — Simplify the testing effort as much as possible. After all, it’s made for automation. Take advantage of it!

Hope that you find this list helpful. Don’t hesitate to comment and suggest more points to add.

P.S. Lots of thanks to Mathieu Fenniak for the inspiration.