API consumers make mistakes with your API. In most cases it's not their fault, but yours.

Focus on design

One way to help developers to avoid mistakes is to focus on the design of your API. If you really want to be anti-developer API provider you apply all anti-pattterns to the design. Some of the antipatterns are: No Versioning, No documentation, No security, No scalability, No logs, No customer service, with REST APIS use POST in everything, nevermind the standard status codes(invent own), use different formatting in parameter names in endpoints…

The anti antipattern is to do design first and test it with the consumers before implementation. That way you can get rid of the silly things and obvious spots where the consumer might make a mistake. Really hip and cool use the documentation-first approach described just recently.

Get the documentation right

Of course you don’t put the antipatterns is use. You put effort in the design and testing the API with clients. But that’s not the end. Another spot where you can mess things up is the documentation. Good documentation helps the developer to find answers to questions but also avoid mistakes. We all want to shine and get things done. Good documenation helps us to shine. I’m kind of obsessed with the topic (API documentation) since it’s one of the top 3 things to manage pretty damn well.

Good documentation:

We all want to make best possible result, but sometimes for various reasons we don’t achieve the best possible. You should not buy a new whip and slash your back like a really hardcore religious believer. Have some mercy and look for more productive solutions.

Documentation is hard

Writing good documentation is not a walk in the park. It’s frigging hard. One of the reasons is that developers use tools and services created by other developers. None of us have the talent of mind reading. Thus we can’t always write instructions to others so that they all understand it similarly every time and every place. That sounds obvious but we tend to forget it. What can you do then to find out what to improve?

Analyze the API usage to find patterns

Since we are not mind readers, we have to find another way to write better documentation. You are most likely tracking the usage of APIs anyway (are you?). Analyse how your customers use your APIs. Don’t just look at the big numbers and pop up champagne every morning due to popularity. That big number might be false news. Your API consumers might be using the API inefficiently and thus make “mistakes” in code. At the same time it seems that our APIs are used a lot! It is true, APIs are used a lot, but in a manner which is not optimal for you or the consumer. Keep the bubbly in the fridge and get back to work!

Your duty as API provider is to help the developer use your product as efficiently as possible. Otherwise they just consume more bandwith and processing power (you are burning money). You need bigger mass of API events for the analysis. You should seek patterns and then look at those to find the ones that are unwanted patterns. Some of the patterns might raise design issues but also unwise use of your API.

Another thing to look for from the analysis is to find odd patterns for some specific consumer. Consumer can often be identified by API key or bearer token. If for example one consumer is making a lot of API calls to one API and that is not what you have thought in use cases, then analyse the patterns of the user. It might be that the consumer is using the endpoint or multiple endpoints inefficiently. You should carefully contact the consumer and ask for more details. There might also be a use case you have not considered and your API is not offering more efficient way to get the consumer’s problem solved.

In addition to educating one developer at a time to use your APIs more wisely, you can add more hints to the documentation. Or writee more detailed story in other part of the documenation and then link it to specific spots in the API documentation.

Some more to read from 100 Days DX