WIP: Documenting an API standard #403

aaronrussellHO · 2024-04-09T10:19:23Z

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

docs/standards/documenting-an-api.md

daniel-ac-martin · 2024-04-22T15:50:04Z

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 · 2024-04-22T15:50:55Z

We might also want to think about GraphQL.

daniel-ac-martin · 2024-04-22T15:55:12Z

docs/standards/documenting-an-api.md

aaronrussellHO · 2024-04-23T09:53:19Z

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.

docs/standards/documenting-an-api.md

aaronrussellHO · 2024-06-04T09:51:21Z

To be included:

How raise an issue
Information about rate limits

Co-authored-by: Daniel A.C. Martin <daniel-ac-martin@users.noreply.github.com>

Co-authored-by: Jeff Horton <87995501+jeff-horton-ho-sas@users.noreply.github.com>

aaronrussellHO · 2024-08-06T09:27:44Z

docs/standards/documenting-an-api.md

+
+Listing our APIs contributes to the government community as well as other organisations and wider industry. Listing our APIs here will also help inter-departmental data exchanges, as well as sharing best practice in API development.
+
+If your API is for internal or team use only, then it should be included in the internal API register.


Suggested change

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

aaronrussellHO · 2024-08-06T09:29:04Z

docs/standards/documenting-an-api.md

+- [You MUST document how to raise an issue with your API](#you-must-document-how-to-raise-an-issue-with-your-api)
+- [You MUST document information on rate limits](#you-must-document-information-on-rate-limits)
+
+### You MUST include your API on the relevant registers


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 · 2024-08-06T09:46:50Z

docs/standards/documenting-an-api.md

+
+### You MUST document information on rate 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.


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.

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

Add to opening paragraph.

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.

aaronrussellHO requested a review from a team as a code owner April 9, 2024 10:19

aaronrussellHO changed the title ~~WIP: Documenting an API standard~~ Documenting an API standard Apr 22, 2024

aaronrussellHO changed the title ~~Documenting an API standard~~ WIP: Documenting an API standard Apr 22, 2024

daniel-ac-martin reviewed Apr 22, 2024

View reviewed changes

docs/standards/documenting-an-api.md Outdated Show resolved Hide resolved