Note Canvas is a web application where you can store all your notes! Click the button below to sign up; registration is instant!
Sign Up For Free Here!
Posted 3 months ago
Go Back

Are you a victim of terrible API documentation?

Have you ever been frustrated at an API's documentation?

Have you ever wanted to smash your monitor out of frustration from dealing with an API?

Have you ever searched for hours looking for specific cases in which an API endpoint you're testing gets some error that's undocumented?

If any of the above applies to you, then you are probably a victim of crappy API implementation!

You deserve compensation of a year's worth of coffee, or perhaps the payment for a shrink because of the mental breakdown you experienced while trying to make this API work.

On a more serious note however, frustration in API documentations and API testing is very common amongst developers. Countless articles have been made regarding the anguish that developers face when dealing with these lousily-documented/lousily-created API's for any multitude number of reasons.

There are actually a lot of reasons that API's can be terrible, and the scope of an entire API architecture's terrible-ness can be pretty wide. This article aims to highlight what not to do, so that API implementations can follow the path of least resistance for easy-to-read API documentation, and easy-to-do API implementation. This is based on what I believe to be the most common reasons developers get stuck on implementing API interactions.

The commandments

Without further ado, here's a list of rules to follow:

  • Thou shalt not.... give vague error messages

    More often than not, people who test your API will run into errors, especially if there are a lot of different test cases for any one particular API endpoint.

    Giving out appropriate error messages helps a testing developer realize what his error is. Sometimes it might be the developer; sometimes it might be the backend getting an error exception for something that wasn't accounted for in the documentation. Nevertheless, giving out the correct error message helps the developer deduce what the problem is and how to prevent that problem from occurring in the future.

    Furthermore, error codes should be precise, and follow conventions on error codes, as listed here. Some examples:

    • 100 Continue
    • 200 OK
    • 201 Created
    • 202 Accepted
    • 400 Bad Request
    • 401 Unauthorized
    • 500 Internal Server Error
    • 501 Not Implemented

  • Thou shalt.... give a clear representation of access/privileges based on type of user(or group type)

    Looking at you, Microsoft Graph Documentations.

    Let me tell a personal story. When I first started using Microsoft Graph (Microsoft Teams' branch of API's), it took me about an hour to find out that personal(i.e. non-Microsoft Business-made) accounts weren't able to use pretty much every Microsoft Graph API endpoint. The only reason I found out was when I saw the list of permissions, and realized it was like this for pretty much all those other endpoints.

    Uploaded Image

    Let's be charitable to Microsoft a little. It did in fact say that it wasn't supported for personal Microsoft accounts, and perhaps I am a moron for taking that long to find out this fact the first time.

    However, I believe this should be much more emphasized, especially for developers (that are new to Microsoft's API architecture) who just found out that they have to register a business account to be able to test these methods. The signup for a free business account is also hard to find, but that's a digression.

    In general, API documentations that have user-based privileges should be crystal clear on what type of things certain user groups can and can't do. Developers don't really have an idea of what the structure of user privilege is unless it's explained--although they might have an inkling based on the sensitivity of data that the API endpoint involves.

    Some of the most common reasons developers get stuck in implementing in this scenario is because they're not really sure 1) what the structure of user permissions are, 2) as mentioned, the documentation doesn't emphasize what user privileges are needed to "unlock" this endpoint, and 3) even if they have a "user group" manager that toggles permissions on, it still doesn't allow the API use because of some overriding exception that is not documented, or explained clearly.

  • Thou shalt not.... ask for certificates as an authorization method

    Looking at you, Google server-to-server request authentications. 

    In general, asking for certificates as an authentication is a pain in the rear, as most developers have no idea how to implement, or even understand how certificates work in detail. If they have no experience in cryptography, chances are, all they know is that it's a mechanism to confirm that the website they're visiting is actually the website that they intend to visit, in somewhat vague sense. 

    There are also issues regarding limitations of privilege. Most environments don't allow for implementation of certs without special access, or developers on a project (especially on enterprise/corporate) are only granted certain permissions.

    And let's not even talk about the process of renewing said certificate.

  • Thou shalt not... implement what's meant to be a list of data as properties of an object

    Uploaded Image
    taken from  

    I don't know about you, but i've seen this quite often. I believe that the reason developers implement what are supposed to be lists, or arrays, like this is so that items can be grabbed by their keys instead of using an arbitrary index. However, I believe that this is a minority case, and nevertheless bad code structure. People usually just iterate through the list, and then filter based on some type of key identifier.

    The problem is, some languages or response-handling frameworks have a strict object structure, and iterating through object properties (like the above JSON response would require) is something that might require a tacky solution.

  • Thou shalt not... structure your API documentation's pages in a decentralized way.

    As a general term, decentralized is good for governments and shipping routes. Very, very unintuitive for API documentations, however.

    To be as precise as possible, in this scenario, decentralized means that API endpoints are explained in separate pages, or even separate documentation sets altogether. Most guilty of this is Microsoft Graph.

    The general goal here is to make searching for API endpoints as quickly as possible. 

    A good example of this is Stripe's API.

    Uploaded Image

    The entire documentation is in a single page application, and they even have their own custom "Find" UI to quickly find whatever documentation you're looking for. You can tell that they have put a lot of effort into making this user-friendly, and making whatever the user wants to know, easy to find. 

    On the other hand, Microsoft Teams is exactly what I described earlier. Their documentation is on separate pages, and it's hard to search for what you want specifically. I searched "teams" on their search bar (implying Microsoft Teams), and this is what I got:

    Uploaded Image

    It's not searching only in the documentation. Instead, it's searching in all the articles related to "Microsoft Teams", which is not what i'm looking for. It's incredibly unintuitive, and it's quite clear that making searches easy was not something that they prioritized.

    Having to look for an API endpoint's documentation is, believe it or not, something that can take up quite a bit of time, especially if you're dealing with a lot of them at once, or are new to the API.

Final Thoughts

This is admittedly a pretty long article. However the instances and evidence for bad API documentation and implementation is plenty, and deserves a stern, well thought-out rebuke. My aim was to point out the API implementation practices that stump developers the most, from personal experience, and I hope I did just that convincingly.


Notice: you can comment as a guest. Just click "Name", then check the "I'd rather post as a guest" option.

Note Canvas is a web application where you can store all your notes! Click the button below to sign up; registration is instant!
Sign Up For Free Here!