7 deadly REST API sins

Sharath S
Sharath S
Nov 19, 2018 · 3 min read

Like with everything else not all APIs are made equal. Some are sinners and others saints. So here are the seven deadly sins you should be aware of when building or consuming APIs:

  1. Change in behaviour — When the API producer has changed the behaviour of an API with no prior notice, the API producer has committed a deadly sin. This can take several shapes and forms but some examples are changing the response status codes, completely changing response body models, introducing new mandatory request parameters etc. all while still maintaining the same API version number.
  2. Non-standard response codes — Probably nothing is more confusing when an API responds with a 200 but then sticks an error message in the response body. Its a sin to not use each of the (atleast) popular status codes such as 200, 202, 304, 400, 409, 403, 404,500 etc. correctly.
  3. PUT and POST APIs but no GETs (or UI) — This is another cardinal sin. To provide an API that allows you to create or modify a resource and then to not allow any form of confirmation of this creation or modification. No user interface is present and no GET API is available. Worse there is no access to logs either. How is one supposed to troubleshoot problems?
  4. Poor documentation — This is a sin that a large majority of API producers commit. Either the documentation poorly describes OR omits all the various parameters, request and response objects OR provides misleading documentation of the API’s behaviour. The documentation sometimes is not organised well leading to consumers missing important endpoints. Also, seldom are common use-cases for the APIs documented e.g. using multiple of the API endpoints together in a sequence to accomplish a task such as submitting an order. If a human has to explain an API and how to use it, the documentation has not served its purpose.
  5. Lack of a sandbox/testing environment — This is a big one. The complete lack of a sandbox environment ( or making it prohibitively expensive to get one ) to test out the APIs.
  6. Multiple ways to do the same thing — A major source of enormous confusion is providing consumers with numerous options to do the same thing with no clear guidance on how/which APIs to pick based on their use-case or roadmap. This especially happens when the API producer has undergone M&A activity and now as a result has got conflicting and overlapping functionality. This can also happen through poor API design, versioning and management of change.
  7. Poorly production tested APIs — This is the most deadly one. When an API hasn’t been tested for the usual expected load in production and spikes, and the consumer is subject to erratic behaviour in the form of timeouts, long response times, error responses that don’t make any sense, the ultimate sin has been committed — not providing the quality of service that consumers expect or were promised. Graceful handling of failures and error conditions is an expectation of all consumers.

It is nearly 2019 and if you think no API producer commits such ghastly sins anymore, think again. There are large, well known brands and enterprises that are still dishing out these sinful APIs. Stay safe!

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade