When Building APIs
1. Provide Success Sample Response, Error Sample Response, all the types and example code. Make sure these samples either have the types or show all cases. If it is like status = “success” then I assume there is a status = “cancelled” but I will never know unless you show me the filed or provide types that go beyond string for that field.
2. Offer clearly what the user seeks on top of the page. Details as one scrolls done. Have an index so anyone can jump quickly.
3. Keep documentation up to date. Have Video tutorials, getting started guides, explainers of concepts and written documentation stating all the workings and assumptions made by the route
4. list all the inputs and outputs with description (you could use natspec comments and doc generate, or similar) just like Helm Chart value descriptions if properly done
5. Have a developer support contact option at the bottom of each page as well as a link to a playground if available or a “free trial” offering
6. Have full built easy, intermediate and advanced examples showing off great use cases with video and technical deep dives going through the build highlighting the why, how and concepts behind the use case as well as the technology used to build.
7. Keep documentation, guides and samples up to date. If possible enforce on each commit to the API.
Why does this matter? The 2024 Stackoverflow survey shows what 50.000 developers think and it cleary states the above is the golden rule.
Generally this is a rough outline, and thoughts quickly jotted down. I haven't wrote this into a full blogpost, but think it's too valuable to keep in Notes.
If you need to improve your API Documentation or need help building happy to work with you and get it done for you. Check out https://dtech.vision and Let's talk.
