API userdocs

OpenCodelists has a RESTful API for interacting with codelists and related resources. Most clients are OpenSAFELY CLI or services, but we are aware of at least one tool a researcher created that uses the API (here).

Probably userdocumentation of the API should provide and overview of what the API is and list each API and its parameters, inputs and outputs and include usage examples.

There's a risk that the docs get out of sync with the code. Ideally parts of this would be generated automatically from the source, perhaps with a tool like pydoc-markdown, mkdocstrings, or sphinx-autoapi.

Part of the Open nature of the site should be that its public API is well-documented. This can assist more potential users in benefiting from the site by integrating it into their tooling and scripting. This also fits with exploring how OpenCodelists might become a product with its own identity somewhat distinct from OpenSAFELY.

Start by inventorying the RESTful API's codelist and related-resource endpoints, including their parameters, inputs, outputs, and representative usage. Compare the available source documentation tools, then define an approach that keeps the user documentation aligned with the code and covers the API overview and examples.