CCM-12523 - Updates after APIM Review

Author: nhsd-david-wass

sandbox/HealthcheckEndpoint.json

@@ -8,7 +8,7 @@
           "description": "Service is healthy"
         }
       },
-      "summary": "Health check endpoint"
+      "summary": "Health check"
     }
   }
 }

sandbox/api/openapi.yaml

@@ -94,7 +94,7 @@ async function patchLetterResponse(request) {
 
 async function postLettersResponse(request) {
   const patchLetterFileMap = {
-    'data/examples/postLetter/requests/postLetters.json': {responsePath: 'data/examples/postLetter/responses/postLetters.json', responseCode: 200},
+    'data/examples/postLetter/requests/postLetters.json': {responsePath: 'data/examples/postLetter/responses/postLetters.json', responseCode: 202},
   };
   return await mapExampleResponse(request, patchLetterFileMap);
 }
@@ -110,7 +110,7 @@ async function postMIResponse(request) {
 
 async function getLetterDataResponse(id) {
   const getLetterDataFileMap = {
-    '2AL5eYSWGzCHlGmzNxuqVusPxDg' : {responsePath: 'http://example.com', responseCode: 303},
+    '2AL5eYSWGzCHlGmzNxuqVusPxDg' : {responsePath: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf', responseCode: 303},
     '2WL5eYSWGzCHlGmzNxuqVusPxDg' : {responsePath: 'data/examples/errors/responses/resourceNotFound.json', responseCode: 404},
   };
   return mapExampleGetResponse(id, getLetterDataFileMap);

sandbox/utils/ResponseProvider.js

@@ -1,38 +1,52 @@
 ## Overview
 
-API for letter suppliers to integrate with NHS Notify.
+Use this API to retrieve letters to be printed.
 
 This API lets you:
 
-* Get lists of letters allocated to you
-* Download letter PDFs and metadata
-* Update and manage letter statuses
-* Submit and retrieve management information (MI)
+* get lists of letters allocated to you
+* download letter PDFs and metadata
+* update and manage letter statuses
+* submit and retrieve management information (MI)
 
 This specification represents the in-development 'next' version of the API schema
-and should be treated as unstable
-
-Use this API to retrieve letters to be printed
+and should be treated as unstable.
 
 ## Who can use this API
 
- The NHS Notify Supplier API is designed for approved print service suppliers who support the delivery of physical letters through the [NHS Notify](https://digital.nhs.uk/services/nhs-notify) platform.
+The NHS Notify Supplier API is designed for approved print service suppliers who support the delivery of physical letters through the [NHS Notify](https://digital.nhs.uk/services/nhs-notify) platform.
 
-## Related APIs
+## Access Modes
 
-The [NHS Notify API](https://digital.nhs.uk/developer/api-catalogue/nhs-notify) is used to send messages to citizens via NHS App, email, text message or letter.
+This API has one access mode. It is:
+
+* restricted access
+
+### Restricted access
+
+This access mode is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate and authorise the calling application but not the end user.
+
+Authentication and authorisation of end users is the responsibility of your application.
+
+To use this access mode, use this security pattern:
+
+* [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)
 
 ## API status and roadmap
 
 This API is [in production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). We are onboarding partners to use it.
 
 We may make additive non-breaking changes to the API without notice, for example the addition of fields to a response or callback, or new optional fields to a request.
 
-## Service Level
+## Service level
 
 This service is a [silver](https://digital.nhs.uk/services/reference-guide#service-levels) service, meaning it is available 24 hours a day, 365 days a year and supported from 8am to 6pm, Monday to Friday excluding bank holidays.
 For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).
 
+## Rate limits
+
+The default rate limit is 300TPS (Transactions Per Second), per app. If you require a higher rate limit please [contact us](https://digital.nhs.uk/developer/help-and-support). or raise this during the onboarding process.
+
 ## Technology
 
 This API is a [REST-based](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest) API.
@@ -62,15 +76,25 @@ This API is available on the internet and, indirectly on the [Health and Social
 
 For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).
 
-## Security and authorisation
+## Errors
 
-This API is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate the calling application but not the end user.
+We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:
 
-Authentication and authorisation of end users is the responsibility of your application.
+* 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
+* 400 to 499 if it failed because of a client error by your application
+* 500 to 599 if it failed because of an error on our server
 
-To access this API, use the following security pattern:
+Errors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.
 
-* [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)
+Your API-calling application should have a mechanism to automatically try again, for example by giving status information to your end user, before giving up. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#error-handling) for more information about error handling.
+
+## Open source
+
+You might find the following [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) resources useful:
+
+| Resource                  | Description                                                          | Links                                                                          |
+|---------------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------|
+| Notify Supplier API       | Source code for the API proxy, sandbox and specification.            | [GitHub repo](https://github.com/NHSDigital/notify-supplier-api) |
 
 ## Environments and testing
 
@@ -91,7 +115,7 @@ Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentat
 
 For details of sandbox test scenarios, or to try out sandbox using our 'Try this API' feature, see the documentation for each endpoint.
 
-Alternatively, you can try out the sandbox using our Postman collection
+Alternatively, you can try out the sandbox using our Postman collection.
 
 You can find our postman collection source in our [public repository on github](https://github.com/NHSDigital/nhs-notify-supplier-api/tree/main/postman).
 
@@ -105,16 +129,28 @@ Our integration test environment:
 
 You need to get your software approved by us before it can go live with this API.
 
-You will also need to follow our steps to - TBD
-
 ### Production smoke testing
 
 Before go-live, you must complete a smoke test in the NHS Notify production environment.
 The smoke test confirms that your live credentials, connectivity, and print workflow operate correctly end-to-end. It will be carried out in coordination with the NHS Notify Supplier API team.
-You will retrieve and print one or more live test letters through the production API, send the printed output to the address provided, and submit a Management Information (MI) update for verification.
+
+The process is as follows:
+
+* retrieve and print one or more live test letters through the production API.
+* send the printed output to the address provided.
+* submit a Management Information (MI) update for verification.
+
 The NHS Notify team will configure your production access, review your results, and confirm that your output meets NHS Notify print specifications.
 
-### Onboarding
+## Onboarding
 
 You need to get your software approved by us before it can go live with this API.
-You will also need to be an approved NHS letter supplier under the framework agreement (ADD link) and nominate your technical and operational contacts
+You will also need to be an approved NHS letter supplier under the framework agreement and nominate your technical and operational contacts
+
+## Related APIs
+
+The [NHS Notify API](https://digital.nhs.uk/developer/api-catalogue/nhs-notify) is used to send messages to citizens via NHS App, email, text message or letter.
+
+## Contact us
+
+For help and support connecting to our APIs and to join our developer community, see [Help and support building healthcare software](https://digital.nhs.uk/developer/help-and-support).

specification/api/components/documentation/APIDescription.md

@@ -1,10 +1,10 @@
 ## Overview
 
-Use this endpoint to send management or operational metrics relating to letter processing and print fulfilment
+Use this endpoint to send management or operational metrics relating to letter processing and print fulfilment.
 
-When you submit a create management information request, the endpoint will respond with a c201 (Created) response code along with the created data including a unique id for the record or an unsuccessful (4xx/5xx) response
+When you submit a create management information request, the endpoint will respond with a 201 (Created) response code along with the created data including a unique id for the record or an unsuccessful (4xx/5xx) response.
 
-Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later
+Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later.
 
 ## Sandbox test scenarios
 

specification/api/components/documentation/createMI.md

@@ -2,13 +2,13 @@
 
 Use this endpoint to get letter data, including downloading the letter's print-ready PDF file.
 
-Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later
+Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later.
 
 ## Sandbox test scenarios
 
 You can test the following scenarios in our sandbox environment.
 
 |Scenario|Request ID|Response|
 |--------|-------|--------|
-|Success  | 2AL5eYSWGzCHlGmzNxuqVusPxDg | Returns 303 (See Other) and URL to [http://example.com](http://example.com) in the Location header |
-|Not Found |2WL5eYSWGzCHlGmzNxuqVusPxDg | Returns 404 Not found and error details in the response |
+|Success  | 2AL5eYSWGzCHlGmzNxuqVusPxDg | Returns 303 (See Other) and URL to an example PDF in the Location header |
+|Not found |2WL5eYSWGzCHlGmzNxuqVusPxDg | Returns 404 Not found and error details in the response |

specification/api/components/documentation/getDataId.md

@@ -2,7 +2,7 @@
 
 Use this endpoint to get the current status of a single letter by its ID.
 
-Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later
+Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later.
 
 ## Sandbox test scenarios
 

specification/api/components/documentation/getLetterStatus.md

@@ -9,4 +9,4 @@ You can test the following scenarios in our sandbox environment.
 |Scenario|Request ID|Response|
 |--------|-------|--------|
 |Success  | 2AL5eYSWGzCHlGmzNxuqVusPxDg | Returns 200 (OK)|
-|Not Found |2WL5eYSWGzCHlGmzNxuqVusPxDg | Returns 404 (Not found) |
+|Not found |2WL5eYSWGzCHlGmzNxuqVusPxDg | Returns 404 (Not found) |

specification/api/components/documentation/headDataId.md

@@ -5,4 +5,4 @@ Use this endpoint to poll letters which are ready to be printed.
 Returns letters whose `status` is **PENDING**.
 Use `limit` to control list size (max 2500).
 
-Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later
+Rate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later.

specification/api/components/documentation/listLetters.md

@@ -13,7 +13,6 @@ Allowed `status` values that can be used to are:
 - `ACCEPTED`
 - `CANCELLED`
 - `DELIVERED`
-- `DESTROYED`
 - `DISPATCHED`
 - `ENCLOSED`
 - `FAILED`