WIP: Documenting an API standard

[aaronrussellHO]

Code change

I can confirm:

Accessibility considerations

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

Content change

• Please review the accessibility checks for content changes.

I can confirm:

• Content does not include any code or configuration changes (excluding frontmatter information)
• Content meets the content standards
  e.g. Writing a principle and Writing a standard
• 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
• 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

[aaronrussellHO]

Suggested change

If your API is for internal or team use only, then it should be included in the internal API register.

[aaronrussellHO]

Suggested change

	### You MUST include your API on the relevant registers
	### You MUST include your API on the relevant registers if your API is public

[aaronrussellHO]

Suggested change

	Rate limiting is important to secure your API and consumers may want to query your API often, so documenting the rate limits helps consumers build their software around these limits.
	Rate limiting is important to secure your API and consumers may want to query your API often, so documenting the rate limits helps consumers build their software around these limits. This information may not want to be shared widely if rate limiting is in place for security reasons.

[aaronrussellHO]

Add where appropriate to sharing parts of the documentation more widely.

[aaronrussellHO]

Add to opening paragraph.

[jeff-horton-ho-sas]

If the rate limit being public is enough to make your application insecure, then it's not an adequate security measure. A malicious user can deterimine the limit through trial and error. Publishing the limit is not the issue, and makes your API harder to use for legitimate consumers.

A project can justify not meeting any part of any standard if their circumstances warrant it. This doesn't need to be a loophole encouraged by the standard.