Designing and maintaining an API standard #417
Conversation
aaronrussellHO
changed the title
Co-authored-by: VictorAlegianiSagnottiHO <[email protected]>
…neering-guidance-and-standards into 415-maintaining-an-api
| --- | ||
|
|
||
| --- |
There was a problem hiding this comment.
We expect that there should be an overarching description for the standard here. If you are happy that the rest of the standard is largely nailed down then you can get this written in (if you are still looking to solidify other parts then it can wait).
https://engineering.homeoffice.gov.uk/standards/writing-a-standard/
|
|
||
| ### You MUST use appropriate nouns for resource names | ||
|
|
||
| Your API resources must follow RESTful resource naming standards as outlined on the restful API [resource naming page](https://restfulapi.net/resource-naming/). |
There was a problem hiding this comment.
Do we expect people developing other types of API (e.g. GraphQL) to follow the same naming convention? If so then I would make that clear
|
|
||
| Knowing how your API scales helps to make sure your API is resilient, can handle peaks of traffic. | ||
|
|
||
| Often using stateless approach to designing an API can help horizontally scale an API. Using techniques such as asynchronous code, multithreading and an event driven approach can all help scale your API. |
There was a problem hiding this comment.
This sentence could be tidied up a little
|
|
||
| ### 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. It helps the team work to the same standards, and it can generate documentation when needed. |
There was a problem hiding this comment.
| Using an API Specification will help define your API endpoints, support is wide, with a wide community using it. It helps the team work to the same standards, and it can generate documentation when needed. | |
| Using an API Specification will help define your API endpoints, support is wide, with a wide community using it. |
Not quite sure what is being said here?
Co-authored-by: edhamiltonHO <[email protected]>
|
|
||
| ## Requirement(s) | ||
|
|
||
| - [You MUST include a form of versioning to your API](#you-must-include-a-form-of-versioning-to-your-api) |
There was a problem hiding this comment.
Might be worth testing these links work somewhere, I can't remember how closely the anchor link needs to match the actual heading in the page below
| - [You MUST consider scalability of your API](#you-must-consider-scalability-of-your-api) | ||
| - [You MUST use an API Specification](#you-must-use-an-api-specification) | ||
|
|
||
| ### You MUST include a form of versioning to your API and consider how you may deprecate a version |
There was a problem hiding this comment.
Would consider whether the point on deprecation would be better in the description of the requirement, would shorten the heading, and could elaborate on it some more
aaronrussellHO
added
standard
content
Software design
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
or
(If the change might impact accessibility then please add some further information here)
Content change
I can confirm:
e.g. Writing a principle and Writing a standard