How good is your API?

Find out how you can make your API more attractive

Andrii Stoialtsev


Everybody knows that documentation is good. Everybody likes good documentation. If it’s really good (well structured, easy to navigate, with plenty of practical examples) — then this is the only thing you need for successful development. However, there is minor but thingy that most software developers don’t like to do — write it.

What is API documentation?

Thanks to other developers (really, thank you guys!) there are many tools which can help us to solve this issue. If you ask any developer this question, in Java world you will probably get the answer — Swagger. Maybe you will hear also RAML or Spring REST Docs and finally Enunciate (I doubt, though).

The nice thing that simplifies our lives is that those libraries allow generating API documentation automatically. In the case of Swagger usage, you add special annotations to your REST controllers so later on they will be added to the documentation. Or, you even might not need to do this if your choice is Spring REST Docs. This guy looks up for all @RestController's in your application and includes them into generating documentation.

Swagger-like documentation format nowadays is taken as defacto standard and essential part of your technical documentation. Especially if you expose it publicly for your consumers.

What else to offer to consumers?

Swagger is good, but not always enough. Of course, it is a nice start for external developers trying to get any useful information about your endpoints. Concise, technical reference.

Even if you have well-outlined endpoints with perfect names, you will be asking how to perform certain operations or how to achieve a specific result. Because when consumers are busy with the integration of your API into their applications, they actually trying to solve their use cases, they try to map the set of operations you offer to their reality.

Write tutorials

Do it, to make consumer onboarding process easier. Here we basically give examples how to implement functional scenarios step by step, e.g. how to create a product, how to fetch all favourite books of a certain author or how to create and manage records in the address book. And so on.

Yes, you have to dedicate some time to it, you have to maintain it as well, but think about how much time it will save you that you could spend on customer (consumer) support (having Swagger already in place). The time that could be used, for instance, for improving processes in your team or automate something.

In addition, good tutorials could give to API consumers a bigger picture, a context of what we as API owners/developers meant, how to use our bunch of endpoints properly. You may think about it as an advanced format of FAQ but for APIs.

All good products have it. So you better too. Just check out a couple of examples from big players:

Honestly saying, guys from Twitter did a great job to have such a rich content of API docs: Documentation (hot topics), API reference index (sort of Swagger style), Tutorials (a bunch of nice practical use cases), Changelog (nice idea to make it public and in a user-friendly format) and API Status.

Types of documentation of Twitter API

You may start with describing most basic topics and consumers will help you write more. Just listen to them when they come to you with their questions. This is your valuable feedback.

And the last thing that I’d like to mention here — making tutorials has no limitations, it a creative process. Just look around, get inspired and make your own. One more creative approach.


This time you help your clients to develop their applications, taking care of writing a specific part of the code which has one goal — effective communication with your API layer.

You will need to run a small survey to figure out which languages (or maybe frameworks) your consumers have in use. Then gather your courage and write client apps in Ruby or Rust, or whatever else you might need. God bless you.

This kind of activity, perhaps, will demand from you even more time than for making tutorials. On the other hand, it would allow reducing amount of time to be integrated with your platform. And will give your consumers a subtle hint of how much you love them.

Sandbox environment

This is a cherry on your API cake. A playground for those who are still looking around which service to use for their needs. Might be a good add-on for your clients to let them model approximate use cases of their business, so they can evaluate the effectiveness of your API and be more prepared for further negotiations.

But think twice, whether you really need it. For most of the cases well maintained Swagger and clean tutorials are more than enough.


In this article, we considered which approaches and tools we can use to improve our API documentation with the aim to provide our consumers with comfortable conditions during the integration process.

In a nutshell, having a technical reference like Swagger is a good start, but keep in mind that you always can do more for your customers. Writing tutorials and/or making SDK for API will improve their user experience significantly.

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