API reference documentation

Context / Problem

When an API is introduced, a backend developer submits a documentation draft covering how the API works, the data objects, and the endpoints.

Most drafts have all the details but miss the nuances — terminology drift, limitations, and errors. Some of those are permanent once the API ships: correcting them later would mean a breaking change.

Approach

In addition to simplifying content, I:

• Tested and documented the limitations and error scenarios described in the API design document.
• Checked field names against the API design guidelines and raised the mismatches with the developer.
• Checked parity between REST and GraphQL: that data types were documented for both.