Research and document an API

Use this early-stage guide to plan and document an API before implementation and release.

Before you start

Ensure you have created a repository for the API, and get the latest version of the repository locally before making changes.

Update the overview file

1. Create a branch of the API's repository for your changes.
2. Locate the overview.md file within the API's resources folder:

   resources/public/api/conf/common/overview.md

3. Update this file with a summary that includes:
   • what the API does (at a high level)
   • its intended use(s) and, if relevant, what it should not be used for
   • versioning information
   • notes on process timing, data availability, and data quality
   • references to related information
   • the general testing approach
   • the general error handling approach

Merge your changes

Open a pull request for the API's repository with a brief description of the changes you've made. Have it approved by a teammate before merging.

Check you've completed this step successfully

The API overview update is successful when the overview text is visible in the API's documentation.