WIP: Documenting an API standard

[aaronrussellHO]

Code change

I can confirm:

Accessibility considerations

• [X] This change will not change layouts, page structures or anything else that might impact accessibility

  Content change

• [X] Please review the accessibility checks for content changes.

I can confirm:

• [X] Content does not include any code or configuration changes (excluding frontmatter information)
• [X] Content meets the content standards e.g. Writing a principle and Writing a standard
• [X] Content is suitable to open source, i.e.:
  • Content does not relate to unreleased gov policy
  • Content does not refer to anti-fraud mechanisms
  • Content does not include sensitive business logic
• [X] Last updated date for content is correct

[daniel-ac-martin]

I think there are some things missing here that we might want to think about:

• What format should be used to document APIs? (e.g. OpenAPI)
• Is a specification enough? (I think it needs to be supplemented with more traditional documentation.)
• Where should the docs live?
• Is it acceptable to generate specifications from implementation code? (I generally prefer a specification-first approach.)
• How should docs be made available? - As a website, or is a raw spec enough? (Maybe this is covered as a part of the catalogues?)

We don't need to have answers to all of those right now, but I think we should bear them in mind.

[daniel-ac-martin]

We might also want to think about GraphQL.

[daniel-ac-martin]

Related:

• API technical and data standards
• Documenting APIs
• Writing API reference documentation

[aaronrussellHO]

I think there are some things missing here that we might want to think about:

• What format should be used to document APIs? (e.g. OpenAPI)
• Is a specification enough? (I think it needs to be supplemented with more traditional documentation.)
• Where should the docs live?
• Is it acceptable to generate specifications from implementation code? (I generally prefer a specification-first approach.)
• How should docs be made available? - As a website, or is a raw spec enough? (Maybe this is covered as a part of the catalogues?)

We don't need to have answers to all of those right now, but I think we should bear them in mind.

We spoke about this in the guild meeting, and some of this we think may be better as a pattern to show how you might want to document something, without been an explicit must.

[aaronrussellHO]

To be included:

• How raise an issue
• Information about rate limits