Designing and maintaining an API standard #417

aaronrussellHO · 2024-05-07T08:59:06Z

Is this pull request a content or a code change? (Please fill in the relevant section and delete the other)

Code change

I can confirm:

Accessibility considerations

Please review the accessibility checks for layout changes.
This change will not change layouts, page structures or anything else that might impact accessibility

or

This change might impact accessibility, automated aXe tests cover the impact

or

This change might impact accessibility and is not covered by automated aXe tests - manual testing has been performed
(If the change might impact accessibility then please add some further information here)

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/designing-and-maintaining-an-api.md

Co-authored-by: VictorAlegianiSagnottiHO <[email protected]>

…neering-guidance-and-standards into 415-maintaining-an-api

docs/standards/designing-and-maintaining-an-api.md

Co-authored-by: edhamiltonHO <[email protected]>

docs/standards/designing-and-maintaining-an-api.md

Co-authored-by: Ed Hamilton <[email protected]>

…neering-guidance-and-standards into 415-maintaining-an-api

jeff-horton-ho-sas

A few clarifications + typos

jeff-horton-ho-sas · 2025-01-31T16:06:51Z

docs/standards/designing-and-maintaining-an-api.md

+
+Using appropiate nouns for resource names rather than actions, because nouns describe the data, and can be used hierarchically to allow a consumer to navigate an API more easily. An example may be to use /devices to list all devices and /devices/:id to list the attributes of a particular device.
+
+Although this advice is given on the [RESTful resource naming page](https://restfulapi.net/resource-naming/) it details a recommended approach to help regardless on type of API (RESTful, GraphQL etc).


Suggested change

Although this advice is given on the [RESTful resource naming page](https://restfulapi.net/resource-naming/) it details a recommended approach to help regardless on type of API (RESTful, GraphQL etc).

Although this advice is given on the [RESTful resource naming page](https://restfulapi.net/resource-naming/) it details a recommended approach to help regardless of the type of API (RESTful, GraphQL etc).

jeff-horton-ho-sas · 2025-01-31T16:08:30Z

docs/standards/designing-and-maintaining-an-api.md

+
+Knowing how your API scales helps to make sure your API is resilient and can handle peaks of traffic.
+
+A stateless API means that the cliant is responsible for providing information about authantication etc. In turn, this means an application can then scale easily horizontally, as it doesn't matter which instance a client connects to.


Suggested change

A stateless API means that the cliant is responsible for providing information about authantication etc. In turn, this means an application can then scale easily horizontally, as it doesn't matter which instance a client connects to.

A stateless API means that the client is responsible for providing information about authentication etc. In turn, this means an application can then scale easily horizontally, as it doesn't matter which instance a client connects to.

jeff-horton-ho-sas · 2025-01-31T16:09:12Z

docs/standards/designing-and-maintaining-an-api.md

+
+A stateless API means that the cliant is responsible for providing information about authantication etc. In turn, this means an application can then scale easily horizontally, as it doesn't matter which instance a client connects to.
+
+Using other techniques such as asynchronous code, multithreading and an event driven approach can also help scale an API.


Suggested change

Using other techniques such as asynchronous code, multithreading and an event driven approach can also help scale an API.

Using techniques such as asynchronous code, multithreading or an event driven approach can help scale an API.

jeff-horton-ho-sas · 2025-01-31T16:16:47Z

docs/standards/designing-and-maintaining-an-api.md

+
+You should also consider how you a version should be depreciated, and communicate this with any consumers.
+
+### You MUST have appropriate status codes returning from each endpoint 


Suggested change

### You MUST have appropriate status codes returning from each endpoint

### You MUST return appropriate status codes from each endpoint

jeff-horton-ho-sas · 2025-01-31T16:17:14Z

docs/standards/designing-and-maintaining-an-api.md

+## Requirement(s)
+
+- [You MUST include a form of versioning to your API](#you-must-include-a-form-of-versioning-to-your-api)
+- [You MUST have appropriate status codes returning from each endpoint](#you-must-have-appropriate-status-codes-returning-from-each-endpoint)


Suggested change

- [You MUST have appropriate status codes returning from each endpoint](#you-must-have-appropriate-status-codes-returning-from-each-endpoint)

- [You MUST return appropriate status codes from each endpoint](#you-must-return-appropriate-status-codes-from-each-endpoint)

jeff-horton-ho-sas · 2025-01-31T16:17:47Z

docs/standards/designing-and-maintaining-an-api.md

+
+Although this advice is given on the [RESTful resource naming page](https://restfulapi.net/resource-naming/) it details a recommended approach to help regardless on type of API (RESTful, GraphQL etc).
+
+### You MUST include some way to observe your API 


Suggested change

### You MUST include some way to observe your API

### You MUST include some way to observe your API

jeff-horton-ho-sas · 2025-01-31T16:18:06Z

docs/standards/designing-and-maintaining-an-api.md

+
+Authentication and authorisation are really important for API, this can mean restricting certain tasks or functions to a limited number of users. A user should have the least privilege possible. Role Based Access Control (RBAC) is an example of how to implement this.
+
+### You MUST test your API 


Suggested change

### You MUST test your API

### You MUST test your API

jeff-horton-ho-sas · 2025-01-31T16:25:23Z

docs/standards/designing-and-maintaining-an-api.md

+
+When maintaining an API we must have a way to make sure that is in good health and there is a way to trace activity.
+
+It is recommended that logs are used however the sensitivity of the data logged must also be considered.


Suggested change

It is recommended that logs are used however the sensitivity of the data logged must also be considered.

Application logs that are sent to an aggregation service are recommended for this. Review [the securing application logging pattern](https://engineering.homeoffice.gov.uk/patterns/securing-application-logging/) if your requests or responses could contain sensitive information.

jeff-horton-ho-sas · 2025-01-31T16:26:09Z

docs/standards/designing-and-maintaining-an-api.md

+
+Using an API Specification will help define your API endpoints, support is wide, with a wide community using it.
+
+A good example is using OpenAPI Swagger to help build, maintain and document your API.


Suggested change

A good example is using OpenAPI Swagger to help build, maintain and document your API.

An example is using [OpenAPI (previously Swagger)](https://www.openapis.org/) to help build, maintain and document your API.

VictorAlegianiSagnottiHO · 2025-01-31T17:07:33Z

docs/standards/designing-and-maintaining-an-api.md

+
+When designing an API aspects such as naming and versioning will help with not only the maintenance of the API, but also help the consumers of your API.
+
+Been clear about how your API can be used, and what is happening can help a consumer build a better applicationby adding proper error messaging as well as using the latest versions of endpoints.


A few typos on this line I think? Been clear, and what is happening, applicationby

dk4g · 2025-01-31T21:10:44Z

docs/standards/designing-and-maintaining-an-api.md

+
+### You MUST use an API Specification
+
+Using an API Specification will help define your API endpoints, support is wide, with a wide community using it.


Suggested change

Using an API Specification will help define your API endpoints, support is wide, with a wide community using it.

Using an API Specification will help define your API endpoints and is widely supported by a large community.

dk4g · 2025-01-31T21:31:01Z

docs/standards/designing-and-maintaining-an-api.md

+
+There are a few [different ways of versioning](https://www.xmatters.com/blog/blog-four-rest-api-versioning-strategies) an API, via the URI path, query parameters or headers. You will also need to decide a versioning strategy, whether that be per endpoint or for the whole API.
+
+You should also consider how you a version should be depreciated, and communicate this with any consumers.


Suggested change

You should also consider how you a version should be depreciated, and communicate this with any consumers.

You should also consider how a version should be deprecated and communicate this to any consumers.

Initial designing and maintaining an API standard

f9fb3d6

aaronrussellHO requested a review from a team as a code owner May 7, 2024 08:59

aaronrussellHO commented May 7, 2024

View reviewed changes

docs/standards/designing-and-maintaining-an-api.md Show resolved Hide resolved

aaronrussellHO commented May 7, 2024

View reviewed changes

docs/standards/designing-and-maintaining-an-api.md Outdated Show resolved Hide resolved

aaronrussellHO commented May 7, 2024

View reviewed changes

docs/standards/designing-and-maintaining-an-api.md Outdated Show resolved Hide resolved

aaronrussellHO commented May 7, 2024

View reviewed changes

docs/standards/designing-and-maintaining-an-api.md Show resolved Hide resolved

aaronrussellHO commented May 7, 2024

View reviewed changes

docs/standards/designing-and-maintaining-an-api.md Outdated Show resolved Hide resolved

aaronrussellHO and others added 3 commits May 14, 2024 09:10

Update docs/standards/designing-and-maintaining-an-api.md

812c4a7

Update docs/standards/designing-and-maintaining-an-api.md

d55a372

Updates following SD guild

2abf83c

aaronrussellHO commented May 14, 2024

View reviewed changes

docs/standards/designing-and-maintaining-an-api.md Outdated Show resolved Hide resolved

Update docs/standards/designing-and-maintaining-an-api.md

4fc8632