📅 21.02.2024
You want API documentation that you can provide to an external developer, ensuring they can work with the APIs with minimal confusion.
After sifting through a heap of API documentations, here are some qualities that I've found beneficial in turning documentation into working code.
Check that the paragraphs in the document form a linear flow that developers can easily follow.
Nothing beats a text-based tutorial for grasping new APIs fast. It should be structured like a cookbook recipe, with each step of the tutorial beginning with what needs to be done and ending with what the outcome should be.
Check out the tutorial section of PostgreSQL documentation and see how mini-tutorials can cover the breath of what you wish to convey.
https://www.postgresql.org/docs/current/tutorial.html
Unless everything is unsecured, nothing meaningful can be done without authentication in place. It's a crucial step that cannot be overlooked.
Invest some time in explaining authentication thoroughly. Don't just simply throw in code snippets or copy-pasted explanations of OAuth.
https://auth0.com/docs/api/authentication#introduction is an example of an API documentation covering authentication well.
Do this:
# Get a list of all accounts
curl --request GET \
--url 'https://dev-loremipsum-example.com/api/accounts' \
--header 'authorization: ...'
# when the page_size is not specified, up to 50 accounts are returned on a page.
curl --request GET \
--url 'https://dev-loremipsum-example.com/api/accounts?page_size=100' \
--header 'authorization: ...'
Don't do this:
Dataset pagination provides a convenient approach to accessing large number of client accounts. By breaking down data into smaller, more manageable chunks, pagination helps in optimizing system performance and enhancing the user experience. If supported by the endpoint, setting the page_size query parameter activates the pagination feature. The complete list of API endpoints that offer pagination feature can be found in Appendix A.2.
I have run into many categories of not so nice surprises , some of which have been:
Availability per region is not covered in detail
Omission of permitted API consumption rates
Data pagination / lack of data pagination
Token expiration
Data inconsistencies between legacy services and new APIs
Version mixing
Each of these issues significantly affected the project's timeline.
No API is perfect. Instead of concealing bad aspects of your APIs beneath layers of text, clearly document them in the early section of your documentation.
Avoid overwhelming new users with prerequisites such as obtaining a real CA certificate, going through time-consuming developer portal registration, etc.