From 1d4269f4117b2af1ace604a7d8666fe1baf20347 Mon Sep 17 00:00:00 2001 From: Aaron Russell Date: Tue, 9 Apr 2024 11:17:35 +0100 Subject: [PATCH 01/11] Inital commit of the Documenting an API standard --- docs/standards/documenting-an-api.md | 66 ++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 docs/standards/documenting-an-api.md diff --git a/docs/standards/documenting-an-api.md b/docs/standards/documenting-an-api.md new file mode 100644 index 00000000..54885e4b --- /dev/null +++ b/docs/standards/documenting-an-api.md @@ -0,0 +1,66 @@ +--- +layout: standard +order: 1 +title: Documenting an API +date: 2024-04-09 +id: SEGAS-XXX +tags: + - Software design + - API Design +--- + +Documenting an API is an important part of the software design lifecycle. It helps consumers of your API, the wider community and even your own team understand the purpose of endpoints, what and how they work, inputs and outputs etc. + +--- + +## Requirement(s) + +- [You MUST include your API on the relevant registers](#you-must-include-your-api-on-the-relevant-registers) +- [You MUST have appropriate status codes returning from each endpoint](#you-must-have-appropriate-status-codes-returning-from-each-endpoint) +- [You MUST have documentation on inputs and outputs of all endpoints](#you-must-have-documentation-on-inputs-and-outputs-of-all-endpoints) +- [You MUST provide specific feedback in responses](#you-must-provide-specific-feedback-in-responses) +- [You MUST use appropriate nouns for resource names](#you-must-use-appropriate-nouns-for-resource-names) + +### You MUST include your API on the relevant registers + +If your API is for internal or team use only, then it should be included in the internal API register. + +if your API is public, it should also be on the [cabinet offices list of API's](https://www.api.gov.uk/ho/#home-office). + +Listing our API's contributes to the government community as welll as other organisations and wider industry. Listing our API's here will also help inter-departmental data exchanges, as well as sharing best practice in API development. + +### You MUST have appropriate status codes returning from each endpoint  + +Your API endpoints must return the relevant status code for each endpoint, for example a 403 if a user doesn't have access. + +It's important that the correct status codes are used as these are recognisable codes and can make it easier to debug for any consumers. + +The Mozilla Foundation has a [definitive list of status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status), and what they mean and do. + +### You MUST have documentation on inputs and outputs of all endpoints + +Documenting the inputs and outputs of endpoints makes it easy for consumers to understand what is required and how to use the given responses from an endpoint. It should also detail an error messages that can be returned and reason for it. + +This can be achieved easily in RESTful API by using Swagger. + +### You MUST provide specific feedback in responses + +It's important that response is clear and gives a brief overview of what has happened when called an endpoint. For example. Access Denied or Cannot connect to database. + +This can make it easier to debug for any consumers. + +A response should not include any information about the technologies used or any internal information for example internal server addresses etc. + +### You MUST use an appropriate method + +Your API endpoints must use a relevant method for each endpoint, for example, using POST for a login endpoint. + +The Mozilla Foundation has a [definitive list of methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), and what they mean and do. + +Using the appropriate methods help to keep endpoints secure as well as helping customers understand how an endpoint should be used, how things should be passed and what the end result will be. + +### 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/). + +--- From e5e58e43c87949623662fface795c8be855da507 Mon Sep 17 00:00:00 2001 From: Aaron Russell Date: Mon, 22 Apr 2024 16:29:50 +0100 Subject: [PATCH 02/11] Small formatting changg --- docs/standards/documenting-an-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/standards/documenting-an-api.md b/docs/standards/documenting-an-api.md index 54885e4b..a1bca17f 100644 --- a/docs/standards/documenting-an-api.md +++ b/docs/standards/documenting-an-api.md @@ -23,12 +23,12 @@ Documenting an API is an important part of the software design lifecycle. It hel ### You MUST include your API on the relevant registers +Listing our API's contributes to the government community as well as other organisations and wider industry. Listing our API's 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. if your API is public, it should also be on the [cabinet offices list of API's](https://www.api.gov.uk/ho/#home-office). -Listing our API's contributes to the government community as welll as other organisations and wider industry. Listing our API's here will also help inter-departmental data exchanges, as well as sharing best practice in API development. - ### You MUST have appropriate status codes returning from each endpoint  Your API endpoints must return the relevant status code for each endpoint, for example a 403 if a user doesn't have access. From dbccbd310da8c33023bfa83269fb1c86cc6c8059 Mon Sep 17 00:00:00 2001 From: Aaron Russell <128606235+aaronrussellHO@users.noreply.github.com> Date: Tue, 23 Apr 2024 10:19:38 +0100 Subject: [PATCH 03/11] Update docs/standards/documenting-an-api.md Co-authored-by: Daniel A.C. Martin --- docs/standards/documenting-an-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standards/documenting-an-api.md b/docs/standards/documenting-an-api.md index a1bca17f..79b4f0e1 100644 --- a/docs/standards/documenting-an-api.md +++ b/docs/standards/documenting-an-api.md @@ -27,7 +27,7 @@ Listing our API's contributes to the government community as well as other organ If your API is for internal or team use only, then it should be included in the internal API register. -if your API is public, it should also be on the [cabinet offices list of API's](https://www.api.gov.uk/ho/#home-office). +If your API is public, it should also be on the [cabinet offices list of API's](https://www.api.gov.uk/ho/#home-office). ### You MUST have appropriate status codes returning from each endpoint  From b1f4588ce06f9776f2b798d9142a979a9323e6ca Mon Sep 17 00:00:00 2001 From: Aaron Russell <128606235+aaronrussellHO@users.noreply.github.com> Date: Tue, 7 May 2024 08:44:28 +0100 Subject: [PATCH 04/11] Update docs/standards/documenting-an-api.md --- docs/standards/documenting-an-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standards/documenting-an-api.md b/docs/standards/documenting-an-api.md index 79b4f0e1..b2ed7349 100644 --- a/docs/standards/documenting-an-api.md +++ b/docs/standards/documenting-an-api.md @@ -9,7 +9,7 @@ tags: - API Design --- -Documenting an API is an important part of the software design lifecycle. It helps consumers of your API, the wider community and even your own team understand the purpose of endpoints, what and how they work, inputs and outputs etc. +Documenting an API is an important part of the software design lifecycle. It helps consumers of your API, the wider community and even your own team understand the purpose of endpoints, what and how they work, inputs and outputs, what the requirements are to access it etc. --- From 76d7bb20a7a1823fdc55a05c68e9651c0e7b4f25 Mon Sep 17 00:00:00 2001 From: Aaron Russell <128606235+aaronrussellHO@users.noreply.github.com> Date: Tue, 7 May 2024 08:46:15 +0100 Subject: [PATCH 05/11] Update docs/standards/documenting-an-api.md --- docs/standards/documenting-an-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standards/documenting-an-api.md b/docs/standards/documenting-an-api.md index b2ed7349..402b1cdf 100644 --- a/docs/standards/documenting-an-api.md +++ b/docs/standards/documenting-an-api.md @@ -41,7 +41,7 @@ The Mozilla Foundation has a [definitive list of status codes](https://developer Documenting the inputs and outputs of endpoints makes it easy for consumers to understand what is required and how to use the given responses from an endpoint. It should also detail an error messages that can be returned and reason for it. -This can be achieved easily in RESTful API by using Swagger. +This can be achieved for a RESTful API by using [OpenAPI (Swagger v3)](https://www.openapis.org/what-is-openapi). ### You MUST provide specific feedback in responses From 7ea4c368f53e56df4faf47c34edcd5b6eefe5863 Mon Sep 17 00:00:00 2001 From: Aaron Russell <128606235+aaronrussellHO@users.noreply.github.com> Date: Tue, 7 May 2024 08:46:55 +0100 Subject: [PATCH 06/11] Update docs/standards/documenting-an-api.md --- docs/standards/documenting-an-api.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/standards/documenting-an-api.md b/docs/standards/documenting-an-api.md index 402b1cdf..cbdcc0c9 100644 --- a/docs/standards/documenting-an-api.md +++ b/docs/standards/documenting-an-api.md @@ -7,6 +7,16 @@ id: SEGAS-XXX tags: - Software design - API Design +related: + sections: + - title: Related links + items: + - text: Minimal documentation set for a product + href: /standards/minimal-documentation-set-for-a-product/ + - text: How to document APIs + href: https://www.gov.uk/guidance/how-to-document-apis + - text: Writing API Reference Documentation + href: https://www.gov.uk/guidance/writing-api-reference-documentation --- Documenting an API is an important part of the software design lifecycle. It helps consumers of your API, the wider community and even your own team understand the purpose of endpoints, what and how they work, inputs and outputs, what the requirements are to access it etc. From d90f2ea3e829ebdc7721b9647f4b4af575e0cad4 Mon Sep 17 00:00:00 2001 From: Aaron Russell Date: Tue, 7 May 2024 08:50:01 +0100 Subject: [PATCH 07/11] Updated API's to APIs --- docs/standards/documenting-an-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/standards/documenting-an-api.md b/docs/standards/documenting-an-api.md index cbdcc0c9..b1dd031c 100644 --- a/docs/standards/documenting-an-api.md +++ b/docs/standards/documenting-an-api.md @@ -33,11 +33,11 @@ Documenting an API is an important part of the software design lifecycle. It hel ### You MUST include your API on the relevant registers -Listing our API's contributes to the government community as well as other organisations and wider industry. Listing our API's here will also help inter-departmental data exchanges, as well as sharing best practice in API development. +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. -If your API is public, it should also be on the [cabinet offices list of API's](https://www.api.gov.uk/ho/#home-office). +If your API is public, it should also be on the [cabinet offices list of APIs](https://www.api.gov.uk/ho/#home-office). ### You MUST have appropriate status codes returning from each endpoint  From 557e4412291c9bec61fe26f5f3a933ccf2a49ea0 Mon Sep 17 00:00:00 2001 From: Aaron Russell <128606235+aaronrussellHO@users.noreply.github.com> Date: Tue, 7 May 2024 08:56:51 +0100 Subject: [PATCH 08/11] Update docs/standards/documenting-an-api.md Co-authored-by: Jeff Horton <87995501+jeff-horton-ho-sas@users.noreply.github.com> --- docs/standards/documenting-an-api.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/standards/documenting-an-api.md b/docs/standards/documenting-an-api.md index b1dd031c..faf23442 100644 --- a/docs/standards/documenting-an-api.md +++ b/docs/standards/documenting-an-api.md @@ -49,7 +49,20 @@ The Mozilla Foundation has a [definitive list of status codes](https://developer ### You MUST have documentation on inputs and outputs of all endpoints -Documenting the inputs and outputs of endpoints makes it easy for consumers to understand what is required and how to use the given responses from an endpoint. It should also detail an error messages that can be returned and reason for it. +Documenting the inputs and outputs of endpoints makes it easy for consumers to understand what is required and how to use the given responses from an endpoint. + +It should include all of the following inputs that apply to your API: + +- Request method +- URI query parameters +- Request headers +- Requirements for the request body + +For each possible response, including error responses, you should document the following: + +- Response status code +- Response headers +- The format of the response body This can be achieved for a RESTful API by using [OpenAPI (Swagger v3)](https://www.openapis.org/what-is-openapi). From 3f47dea3c632c29cfe47835d417fa245be95e53b Mon Sep 17 00:00:00 2001 From: Aaron Russell Date: Tue, 7 May 2024 08:56:36 +0100 Subject: [PATCH 09/11] Added point around connecting to API --- docs/standards/documenting-an-api.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/standards/documenting-an-api.md b/docs/standards/documenting-an-api.md index faf23442..c2a957be 100644 --- a/docs/standards/documenting-an-api.md +++ b/docs/standards/documenting-an-api.md @@ -12,7 +12,7 @@ related: - title: Related links items: - text: Minimal documentation set for a product - href: /standards/minimal-documentation-set-for-a-product/ + href: /standards/minimal-documentation-set-for-a-product/ - text: How to document APIs href: https://www.gov.uk/guidance/how-to-document-apis - text: Writing API Reference Documentation @@ -86,4 +86,8 @@ Using the appropriate methods help to keep endpoints secure as well as helping c Your API resources must follow RESTful resource naming standards as outlined on the restful API [resource naming page](https://restfulapi.net/resource-naming/). +### You MUST document how to connect to your API + +You must have documentation in place explaining how you onboard users to your API, if your API requires authorisation, you must document how to get authentication keys. + --- From f3d7016018835ce014c49ad4b4dacf2692ff73cc Mon Sep 17 00:00:00 2001 From: Aaron Russell Date: Tue, 7 May 2024 08:58:16 +0100 Subject: [PATCH 10/11] Added link to new section --- docs/standards/documenting-an-api.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/standards/documenting-an-api.md b/docs/standards/documenting-an-api.md index c2a957be..b5e25cb1 100644 --- a/docs/standards/documenting-an-api.md +++ b/docs/standards/documenting-an-api.md @@ -30,6 +30,7 @@ Documenting an API is an important part of the software design lifecycle. It hel - [You MUST have documentation on inputs and outputs of all endpoints](#you-must-have-documentation-on-inputs-and-outputs-of-all-endpoints) - [You MUST provide specific feedback in responses](#you-must-provide-specific-feedback-in-responses) - [You MUST use appropriate nouns for resource names](#you-must-use-appropriate-nouns-for-resource-names) +- [You MUST document how to connect to your API](#you-must-document-how-to-connect-to-your-api) ### You MUST include your API on the relevant registers From 9154bf2dd611c28667559530bf3d5304ab230115 Mon Sep 17 00:00:00 2001 From: Aaron Russell Date: Tue, 11 Jun 2024 08:37:31 +0100 Subject: [PATCH 11/11] Updated following guild meeting --- docs/standards/documenting-an-api.md | 32 +++++++++------------------- 1 file changed, 10 insertions(+), 22 deletions(-) diff --git a/docs/standards/documenting-an-api.md b/docs/standards/documenting-an-api.md index b5e25cb1..87aa69a0 100644 --- a/docs/standards/documenting-an-api.md +++ b/docs/standards/documenting-an-api.md @@ -26,11 +26,11 @@ Documenting an API is an important part of the software design lifecycle. It hel ## Requirement(s) - [You MUST include your API on the relevant registers](#you-must-include-your-api-on-the-relevant-registers) -- [You MUST have appropriate status codes returning from each endpoint](#you-must-have-appropriate-status-codes-returning-from-each-endpoint) - [You MUST have documentation on inputs and outputs of all endpoints](#you-must-have-documentation-on-inputs-and-outputs-of-all-endpoints) - [You MUST provide specific feedback in responses](#you-must-provide-specific-feedback-in-responses) -- [You MUST use appropriate nouns for resource names](#you-must-use-appropriate-nouns-for-resource-names) - [You MUST document how to connect to your API](#you-must-document-how-to-connect-to-your-api) +- [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 @@ -40,17 +40,9 @@ If your API is for internal or team use only, then it should be included in the If your API is public, it should also be on the [cabinet offices list of APIs](https://www.api.gov.uk/ho/#home-office). -### You MUST have appropriate status codes returning from each endpoint  - -Your API endpoints must return the relevant status code for each endpoint, for example a 403 if a user doesn't have access. - -It's important that the correct status codes are used as these are recognisable codes and can make it easier to debug for any consumers. - -The Mozilla Foundation has a [definitive list of status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status), and what they mean and do. - ### You MUST have documentation on inputs and outputs of all endpoints -Documenting the inputs and outputs of endpoints makes it easy for consumers to understand what is required and how to use the given responses from an endpoint. +Documenting the inputs and outputs of endpoints makes it easy for consumers to understand what is required and how to use the given responses from an endpoint. It should include all of the following inputs that apply to your API: @@ -69,26 +61,22 @@ This can be achieved for a RESTful API by using [OpenAPI (Swagger v3)](https://w ### You MUST provide specific feedback in responses -It's important that response is clear and gives a brief overview of what has happened when called an endpoint. For example. Access Denied or Cannot connect to database. +It's important that response is clear and gives a brief overview of what has happened when called an endpoint. For example. Access Denied or Cannot connect to database. Your documentation should also state what each status code represents. This can make it easier to debug for any consumers. A response should not include any information about the technologies used or any internal information for example internal server addresses etc. -### You MUST use an appropriate method - -Your API endpoints must use a relevant method for each endpoint, for example, using POST for a login endpoint. +### You MUST document how to connect to your API -The Mozilla Foundation has a [definitive list of methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), and what they mean and do. +You must have documentation in place explaining how you onboard users to your API, if your API requires authorisation, you must document how to get authentication keys. -Using the appropriate methods help to keep endpoints secure as well as helping customers understand how an endpoint should be used, how things should be passed and what the end result will be. +### You MUST document how to raise an issue with your API -### You MUST use appropriate nouns for resource names +It's important to document how to raise an issue with your API, this not only helps your consumers with debugging or raising concerns, but enabled a feedback loop with your users. -Your API resources must follow RESTful resource naming standards as outlined on the restful API [resource naming page](https://restfulapi.net/resource-naming/). +### You MUST document information on rate limits -### You MUST document how to connect to your API - -You must have documentation in place explaining how you onboard users to your API, if your API requires authorisation, you must document how to get authentication keys. +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. ---