API userdocs

[mikerkelly]

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.

[iaindillingham]

Thanks for writing this up, @mikerkelly. From the planning meeting today, I think you created it having spoken to Milan at the OpenSAFELY Symposium. As with #2191, it's not quite urgent or important enough to be addressed during the OpenCodelists initiative, but we can return to it during deck-scrubbing.

Before we do, we should consider whether the OpenCodelists API is public in the sense of "we expect it to be used by clients that weren't created by the tech team".