In my last post, I talked about how I turned my Troyal API design into an OpenAPI spec. Troyal is my fictional API for tracking music and film royalties.
And now, I have completed 3 more tasks.
Firstly, I wrote an error codes guide: When a request fails, developers need to know three things quickly; what went wrong, why, and how to fix it. My guide lists every error the API can return (400, 401, 404 and 429) with a short explanation of the cause and the fix, and it shows exactly what the error response looks like.
Secondly, I added a changelog: A changelog tells developers what changed in each version of an API, so they can see at a glance what's new. Mine lists the first release, 1.0.0, and what's planned next.
Thirdly, I set up a Jira board: I turned each piece of documentation work into a ticket, from the product brief to the OpenAPI spec. Seven are done and five are still to come.…