From bae97128781119efe0fd69408f7862e3caec3b67 Mon Sep 17 00:00:00 2001 From: David Wass Date: Wed, 22 Oct 2025 15:30:33 +0100 Subject: [PATCH 1/4] CCM-12523 - Updates after APIM Review --- sandbox/HealthcheckEndpoint.json | 2 +- sandbox/api/openapi.yaml | 317 ++++++++++++++---- sandbox/utils/ResponseProvider.js | 4 +- .../documentation/APIDescription.md | 82 +++-- .../api/components/documentation/createMI.md | 6 +- .../api/components/documentation/getDataId.md | 6 +- .../documentation/getLetterStatus.md | 2 +- .../components/documentation/headDataId.md | 2 +- .../components/documentation/listLetters.md | 2 +- .../components/documentation/patchLetter.md | 1 - .../components/documentation/postLetters.md | 3 +- .../api/components/schemas/letterStatus.yml | 1 - specification/api/notify-supplier-phase1.yml | 6 +- 13 files changed, 329 insertions(+), 105 deletions(-) diff --git a/sandbox/HealthcheckEndpoint.json b/sandbox/HealthcheckEndpoint.json index c286173f..41f9393e 100644 --- a/sandbox/HealthcheckEndpoint.json +++ b/sandbox/HealthcheckEndpoint.json @@ -8,7 +8,7 @@ "description": "Service is healthy" } }, - "summary": "Health check endpoint" + "summary": "Health check" } } } diff --git a/sandbox/api/openapi.yaml b/sandbox/api/openapi.yaml index abc29494..ec700064 100644 --- a/sandbox/api/openapi.yaml +++ b/sandbox/api/openapi.yaml @@ -1,17 +1,133 @@ openapi: 3.0.3 info: description: | - API for communication suppliers to integrate with NHS Notify. + ## Overview + + API for letter suppliers to integrate with NHS Notify. + + 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) This specification represents the in-development 'next' version of the API schema - and should be treated as unstable. + and should be treated as unstable + + Use this API to retrieve letters to be printed + + ## 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. + + ## 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. + + ## 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 + + 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). + + ## Technology + + This API is a [REST-based](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest) API. + + We follow the [JSON:API](https://jsonapi.org/) standard for our request and response schemas. + + ### Response content types + + This API can generate responses in the following format: + + * `application/vnd.api+json` - see [JSON:API specification](https://jsonapi.org/format/#introduction) + + ### Request content types + + This API will accept request payloads of the following types: + + * `application/vnd.api+json` - see [JSON:API specification](https://jsonapi.org/format/#introduction) + * `application/json` + + The `Content-Type` header may optionally include a `charset` attribute. If included, it **must** be set to `charset=utf-8` Any other `charset` value will result in a `406` error response. If omitted then `utf-8` is assumed. + + If you attempt to send a payload without the `Content-Type` header set to either of these values then the API will respond with a `415 Unsupported Media Type` response. + + ## Network access + + This API is available on the internet and, indirectly on the [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network). + + For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis). + + ## Security and authorisation + + 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. + + Authentication and authorisation of end users is the responsibility of your application. + + To access this API, use the following 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) + + ## Environments and testing + + | Environment | Base URL | + |------------ | -------- | + | Sandbox | `https://sandbox.api.service.nhs.uk/nhs-notify-supplier` | + | Integration test | `https://int.api.service.nhs.uk/nhs-notify-supplier` | + | Production | `https://api.service.nhs.uk/nhs-notify-supplier` | + + ### Sandbox testing + + Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing): + + * is for early developer testing + * only covers a limited set of scenarios + * is stateless, so does not actually persist any updates + * is open access, so does not allow you to test authorisation + + 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 + + You can find our postman collection source in our [public repository on github](https://github.com/NHSDigital/nhs-notify-supplier-api/tree/main/postman). + + ### Integration testing + + Our integration test environment: + + * is for formal integration sandbox-testing + * is stateful, so persists updates + * includes authorisation via [signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) + + 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 NHS Notify team will configure your production access, review your results, and confirm that your output meets NHS Notify print specifications. + + ### 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 title: NHS Notify Supplier API version: next servers: +- description: Public sandbox + url: https://internal-dev-sandbox.api.service.nhs.uk/nhs-notify-supplier - description: Local development server url: http://127.0.0.1:9000 -- description: Public sandbox - url: https://sandbox-server.nhs.uk/nhs-notify-supplier-api tags: - description: "" name: letter @@ -22,8 +138,15 @@ tags: paths: /letters: get: - description: The key use of this endpoint is to query letters which are ready - to be printed + description: | + ## Overview + + 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 operationId: listLetters parameters: - description: "Unique request identifier, in the format of a GUID" @@ -308,6 +431,35 @@ paths: - letter x-eov-operation-handler: controllers/LetterController post: + description: | + ## Overview + + Use this endpoint to update the status for (example, PRINTED, DISPATCHED, DELIVERED) of multiple letters by providing the new statuses in the request body, optionally including reason codes and text. + + Use this endpoint when you need to report status changes for several letters at once. + + When you make a POST update request with, the endpoint will respond with a successful (202) response code 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. + + ### Statuses + + Allowed `status` values that can be used to are: + + - `ACCEPTED` + - `CANCELLED` + - `DELIVERED` + - `DISPATCHED` + - `ENCLOSED` + - `FAILED` + - `FORWARDED` + - `PRINTED` + - `REJECTED` + - `RETURNED` + + It is not possible to update a letter to status of `PENDING`. + + Optionally a `reasonCode` and `reasonText` explaining the status (for example, validation failures) can be included in the request body for each update. operationId: postLetters parameters: - description: "Unique request identifier, in the format of a GUID" @@ -362,25 +514,25 @@ paths: id: 2WL5eYSWGzCHlGmzNxuqVusPxDg type: Letter - attributes: - reasonCode: 100 + reasonCode: R01 reasonText: failed validation status: RETURNED id: 2WL5eYSWGzCHlGmzNxuqVusPxDg type: Letter - attributes: - reasonCode: 100 + reasonCode: R01 reasonText: failed validation status: CANCELLED id: 2WL5eYSWGzCHlGmzNxuqVusPxDg type: Letter - attributes: - reasonCode: 100 + reasonCode: R01 reasonText: failed validation status: FAILED id: 2WL5eYSWGzCHlGmzNxuqVusPxDg type: Letter - attributes: - reasonCode: 100 + reasonCode: R01 reasonText: failed validation status: RETURNED id: 2WL5eYSWGzCHlGmzNxuqVusPxDg @@ -467,9 +619,14 @@ paths: /letters/{id}: get: description: | - ## Get details the status of a letter. + ## Overview + + 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 ## Sandbox test scenarios + You can test the following scenarios in our sandbox environment | Scenario | Letter Id | @@ -607,8 +764,33 @@ paths: - letter x-eov-operation-handler: controllers/LetterController patch: - description: Update the status of a letter by providing the new status in the - request body. + description: | + ## Overview + + Use this endpoint to update the status of a letter by submitting the new status in the request body, optionally providing a reason code and text. + + When you make a PATCH request with your application, the endpoint will respond with a successful (200) response code, along with the updated patient resource 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. + + ### Statuses + + Allowed `status` values that can be used to are: + + - `ACCEPTED` + - `CANCELLED` + - `DELIVERED` + - `DISPATCHED` + - `ENCLOSED` + - `FAILED` + - `FORWARDED` + - `PRINTED` + - `REJECTED` + - `RETURNED` + + It is not possible to update a letter to status of `PENDING`. + + Optionally a `reasonCode` and `reasonText` explaining the status (for example, validation failures) can be included in the request body. operationId: patchLetter parameters: - description: "Unique request identifier, in the format of a GUID" @@ -671,7 +853,7 @@ paths: value: data: attributes: - reasonCode: 100 + reasonCode: R01 reasonText: failed validation status: REJECTED id: 2WL5eYSWGzCHlGmzNxuqVusPxDg @@ -697,7 +879,7 @@ paths: value: data: attributes: - reasonCode: 100 + reasonCode: R01 reasonText: failed validation status: CANCELLED id: 2WL5eYSWGzCHlGmzNxuqVusPxDg @@ -723,7 +905,7 @@ paths: value: data: attributes: - reasonCode: 100 + reasonCode: R01 reasonText: failed validation status: FAILED id: 2WL5eYSWGzCHlGmzNxuqVusPxDg @@ -733,7 +915,7 @@ paths: value: data: attributes: - reasonCode: 100 + reasonCode: R01 reasonText: failed validation status: REJECTED id: 2WL5eYSWGzCHlGmzNxuqVusPxDg @@ -865,6 +1047,21 @@ paths: x-eov-operation-handler: controllers/LetterController /letters/{id}/data: get: + description: | + ## Overview + + 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 + + ## 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 an example PDF in the Location header | + |Not Found |2WL5eYSWGzCHlGmzNxuqVusPxDg | Returns 404 Not found and error details in the response | operationId: getDataId parameters: - description: Unique identifier of this resource @@ -980,47 +1177,26 @@ paths: tags: - data x-eov-operation-handler: controllers/DataController - head: - operationId: headDataId - parameters: - - description: Unique identifier of this resource - explode: false - in: path - name: id - required: true - schema: - example: 24L5eYSWGzCHlGmzNxuqVusPxDg - type: string - style: simple - - description: "Unique request identifier, in the format of a GUID" - explode: false - in: header - name: X-Request-ID - required: true - schema: - example: dcb9c8dc-c2f4-4d5f-8674-a2e913e040b2 - type: string - style: simple - - description: |- - An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters. If not provided in the request, NHS Notify will default to a system generated ID in its place. - The ID will be returned in a response header. - explode: false - in: header - name: X-Correlation-ID - required: false - schema: - example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA - type: string - style: simple - responses: - "200": - description: OK - summary: Check for the existence of a data file - tags: - - data - x-eov-operation-handler: controllers/DataController /mi: post: + description: | + ## Overview + + 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 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 + + ## Sandbox test scenarios + + You can test the following scenarios in our sandbox environment. + + |Scenario|Request|Response| + |--------|-------|--------| + |Success|Request for successful MI record Creation| 201 (Created) with the created management information in the response| + |Invalid Request|Invalid Request for MI record Creation| 400 (Bad Request) with the error details in the body| + |Unknown specification|Request for MI record Creation for unknown spec|404 (Not Found) with the error details in the body| operationId: createMI parameters: - description: "Unique request identifier, in the format of a GUID" @@ -1124,6 +1300,23 @@ paths: example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA type: string style: simple + "400": + content: + application/vnd.api+json: + examples: + error-bad-request: + value: + errors: + - code: NOTIFY_INVALID_REQUEST + detail: "Invalid request, please refer to the API specifications" + id: rrt-1931948104716186917-c-geu2-10664-3111479-3.0 + links: + about: https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier + status: "400" + title: Invalid request + schema: + $ref: "#/components/schemas/listLetters_400_response" + description: "Bad request, invalid input data" "404": content: application/vnd.api+json: @@ -1224,14 +1417,13 @@ components: - DELIVERED - FAILED - RETURNED - - DESTROYED - FORWARDED example: PENDING type: string reasonCode: description: Reason code for the given status - example: 100 - type: number + example: R01 + type: string reasonText: description: Reason text for the given status example: failed validation @@ -1314,14 +1506,13 @@ components: - DELIVERED - FAILED - RETURNED - - DESTROYED - FORWARDED example: PENDING type: string reasonCode: description: Reason code for the given status - example: 100 - type: number + example: R01 + type: string reasonText: description: Reason text for the given status example: failed validation @@ -1441,7 +1632,7 @@ components: name: apikey type: apiKey x-nhsd-apim: - temporary: true + temporary: false monitoring: false access: [] target: diff --git a/sandbox/utils/ResponseProvider.js b/sandbox/utils/ResponseProvider.js index da0ca8fd..ae6e69e0 100644 --- a/sandbox/utils/ResponseProvider.js +++ b/sandbox/utils/ResponseProvider.js @@ -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); diff --git a/specification/api/components/documentation/APIDescription.md b/specification/api/components/documentation/APIDescription.md index 9a2db448..8b1872a3 100644 --- a/specification/api/components/documentation/APIDescription.md +++ b/specification/api/components/documentation/APIDescription.md @@ -1,26 +1,36 @@ ## 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 @@ -28,11 +38,15 @@ This API is [in production, beta](https://digital.nhs.uk/developer/guides-and-do 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). diff --git a/specification/api/components/documentation/createMI.md b/specification/api/components/documentation/createMI.md index 17aff50e..0063296e 100644 --- a/specification/api/components/documentation/createMI.md +++ b/specification/api/components/documentation/createMI.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 diff --git a/specification/api/components/documentation/getDataId.md b/specification/api/components/documentation/getDataId.md index 81e742e1..c83a9241 100644 --- a/specification/api/components/documentation/getDataId.md +++ b/specification/api/components/documentation/getDataId.md @@ -2,7 +2,7 @@ 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 @@ -10,5 +10,5 @@ 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 | diff --git a/specification/api/components/documentation/getLetterStatus.md b/specification/api/components/documentation/getLetterStatus.md index 257d4d7d..cf4474d1 100644 --- a/specification/api/components/documentation/getLetterStatus.md +++ b/specification/api/components/documentation/getLetterStatus.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 diff --git a/specification/api/components/documentation/headDataId.md b/specification/api/components/documentation/headDataId.md index 66e98407..7770d133 100644 --- a/specification/api/components/documentation/headDataId.md +++ b/specification/api/components/documentation/headDataId.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) | diff --git a/specification/api/components/documentation/listLetters.md b/specification/api/components/documentation/listLetters.md index 337033c7..84cc4160 100644 --- a/specification/api/components/documentation/listLetters.md +++ b/specification/api/components/documentation/listLetters.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. diff --git a/specification/api/components/documentation/patchLetter.md b/specification/api/components/documentation/patchLetter.md index f577051e..ad4dc3cb 100644 --- a/specification/api/components/documentation/patchLetter.md +++ b/specification/api/components/documentation/patchLetter.md @@ -13,7 +13,6 @@ Allowed `status` values that can be used to are: - `ACCEPTED` - `CANCELLED` - `DELIVERED` -- `DESTROYED` - `DISPATCHED` - `ENCLOSED` - `FAILED` diff --git a/specification/api/components/documentation/postLetters.md b/specification/api/components/documentation/postLetters.md index b2ebee69..f968ac6d 100644 --- a/specification/api/components/documentation/postLetters.md +++ b/specification/api/components/documentation/postLetters.md @@ -4,7 +4,7 @@ Use this endpoint to update the status for (example, PRINTED, DISPATCHED, DELIVE Use this endpoint when you need to report status changes for several letters at once. -When you make a POST update request with, the endpoint will respond with a successful (202) response code or an unsuccessful (4xx/5xx) response. +When you make a POST update request with the endpoint, it will respond with a successful (202) response code 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. @@ -15,7 +15,6 @@ Allowed `status` values that can be used to are: - `ACCEPTED` - `CANCELLED` - `DELIVERED` -- `DESTROYED` - `DISPATCHED` - `ENCLOSED` - `FAILED` diff --git a/specification/api/components/schemas/letterStatus.yml b/specification/api/components/schemas/letterStatus.yml index ceeb6f7d..a95551d7 100644 --- a/specification/api/components/schemas/letterStatus.yml +++ b/specification/api/components/schemas/letterStatus.yml @@ -10,7 +10,6 @@ enum: - DELIVERED - FAILED - RETURNED - - DESTROYED - FORWARDED description: The supplier status of an individual letter example: PENDING diff --git a/specification/api/notify-supplier-phase1.yml b/specification/api/notify-supplier-phase1.yml index bccf356e..4062bf09 100644 --- a/specification/api/notify-supplier-phase1.yml +++ b/specification/api/notify-supplier-phase1.yml @@ -31,8 +31,8 @@ paths: - $ref: 'components/parameters/correlationId.yml' get: $ref: 'components/endpoints/getDataId.yml' - head: - $ref: 'components/endpoints/headDataId.yml' + #head: + # $ref: 'components/endpoints/headDataId.yml' /mi: parameters: - $ref: 'components/parameters/requestId.yml' @@ -46,7 +46,7 @@ paths: responses: "200": description: Service is healthy - summary: Health check endpoint + summary: Health check components: securitySchemes: app-level3: From ae46eb749ee3b2ae724605d5a97b66182e186562 Mon Sep 17 00:00:00 2001 From: David Wass Date: Wed, 22 Oct 2025 15:53:35 +0100 Subject: [PATCH 2/4] update md lint rule --- specification/api/components/documentation/APIDescription.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/api/components/documentation/APIDescription.md b/specification/api/components/documentation/APIDescription.md index 8b1872a3..7a6311fe 100644 --- a/specification/api/components/documentation/APIDescription.md +++ b/specification/api/components/documentation/APIDescription.md @@ -145,7 +145,7 @@ The NHS Notify team will configure your production access, review your results, ## 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 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 From 997b1f0aa838b38e7f72ed88cb1b2db7c347e7ec Mon Sep 17 00:00:00 2001 From: David Wass Date: Tue, 4 Nov 2025 15:11:21 +0000 Subject: [PATCH 3/4] remove all references to 'DESTROYED' status --- docs/assets/diagrams/types.md | 4 ++-- docs/collections/_consumers/integration.md | 2 +- internal/datastore/src/types.md | 2 +- internal/datastore/src/types.ts | 2 +- lambdas/api-handler/src/contracts/letters.ts | 1 - scripts/test-data/src/cli/index.ts | 2 -- tests/sandbox/testCases/updateLetterStatus_testCases.ts | 4 ++-- 7 files changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/assets/diagrams/types.md b/docs/assets/diagrams/types.md index 08e72d59..42e62db7 100644 --- a/docs/assets/diagrams/types.md +++ b/docs/assets/diagrams/types.md @@ -1,4 +1,4 @@ -## Data Store Schemas +# Data Store Schemas This document contains the mermaid diagrams for the data store schemas used in the application. @@ -10,7 +10,7 @@ The schemas are generated from Zod definitions and provide a visual representati erDiagram Letter { string id - string status "enum: PENDING, ACCEPTED, REJECTED, PRINTED, ENCLOSED, CANCELLED, DISPATCHED, FAILED, RETURNED, DESTROYED, FORWARDED, DELIVERED" + string status "enum: PENDING, ACCEPTED, REJECTED, PRINTED, ENCLOSED, CANCELLED, DISPATCHED, FAILED, RETURNED, FORWARDED, DELIVERED" string specificationId string groupId number reasonCode diff --git a/docs/collections/_consumers/integration.md b/docs/collections/_consumers/integration.md index 14785e2e..740bb4c0 100644 --- a/docs/collections/_consumers/integration.md +++ b/docs/collections/_consumers/integration.md @@ -105,7 +105,7 @@ The mandatory statuses are: **ACCEPTED**, **REJECTED**, **FORWARDED**, **DISPATC - **CANCELLED:** The letter was cancelled following a request from the NHS Notify team **Optional statuses** - additional, non-mandatory updates that can provide greater operational insight. -The optional statuses are: **PRINTED**, **ENCLOSED**, **DELIVERED**, and **DESTROYED**. +The optional statuses are: **PRINTED**, **ENCLOSED**, and **DELIVERED**. These can be used if your internal workflow supports more granular reporting. - **PRINTED:** The letter has been printed. diff --git a/internal/datastore/src/types.md b/internal/datastore/src/types.md index 0ca598a8..25fde561 100644 --- a/internal/datastore/src/types.md +++ b/internal/datastore/src/types.md @@ -10,7 +10,7 @@ The schemas are generated from Zod definitions and provide a visual representati erDiagram Letter { string id - string status "enum: PENDING, ACCEPTED, REJECTED, PRINTED, ENCLOSED, CANCELLED, DISPATCHED, FAILED, RETURNED, DESTROYED, FORWARDED, DELIVERED" + string status "enum: PENDING, ACCEPTED, REJECTED, PRINTED, ENCLOSED, CANCELLED, DISPATCHED, FAILED, RETURNED, FORWARDED, DELIVERED" string specificationId string groupId number reasonCode diff --git a/internal/datastore/src/types.ts b/internal/datastore/src/types.ts index 1eb1e815..2f2aa810 100644 --- a/internal/datastore/src/types.ts +++ b/internal/datastore/src/types.ts @@ -15,7 +15,7 @@ export type Supplier = z.infer; export const LetterStatus = z.enum([ 'PENDING', 'ACCEPTED', 'REJECTED', 'PRINTED', 'ENCLOSED', 'CANCELLED', 'DISPATCHED', 'FAILED', - 'RETURNED', 'DESTROYED', 'FORWARDED', 'DELIVERED']); + 'RETURNED', 'FORWARDED', 'DELIVERED']); export type LetterStatusType = z.infer; diff --git a/lambdas/api-handler/src/contracts/letters.ts b/lambdas/api-handler/src/contracts/letters.ts index d777018a..a6c0789b 100644 --- a/lambdas/api-handler/src/contracts/letters.ts +++ b/lambdas/api-handler/src/contracts/letters.ts @@ -21,7 +21,6 @@ export const LetterStatusSchema = z.enum([ 'DISPATCHED', 'FAILED', 'RETURNED', - 'DESTROYED', 'FORWARDED', 'DELIVERED' ]); diff --git a/scripts/test-data/src/cli/index.ts b/scripts/test-data/src/cli/index.ts index 0e2a4517..a584c971 100644 --- a/scripts/test-data/src/cli/index.ts +++ b/scripts/test-data/src/cli/index.ts @@ -54,7 +54,6 @@ async function main() { "DISPATCHED", "FAILED", "RETURNED", - "DESTROYED", "FORWARDED", "DELIVERED", ], @@ -132,7 +131,6 @@ async function main() { "DISPATCHED", "FAILED", "RETURNED", - "DESTROYED", "FORWARDED", "DELIVERED", ], diff --git a/tests/sandbox/testCases/updateLetterStatus_testCases.ts b/tests/sandbox/testCases/updateLetterStatus_testCases.ts index 35765676..816a6e83 100644 --- a/tests/sandbox/testCases/updateLetterStatus_testCases.ts +++ b/tests/sandbox/testCases/updateLetterStatus_testCases.ts @@ -112,10 +112,10 @@ export const apiSandboxUpdateLetterStatusTestData: ApiSandboxUpdateLetterStatusT }, expectedStatus: 400, expectedResponse: { - message: 'request.body.data.attributes.status should be equal to one of the allowed values: PENDING, ACCEPTED, REJECTED, PRINTED, ENCLOSED, CANCELLED, DISPATCHED, DELIVERED, FAILED, RETURNED, DESTROYED, FORWARDED', + message: 'request.body.data.attributes.status should be equal to one of the allowed values: PENDING, ACCEPTED, REJECTED, PRINTED, ENCLOSED, CANCELLED, DISPATCHED, DELIVERED, FAILED, RETURNED, FORWARDED', errors: [{ path: '.body.data.attributes.status', - message: 'should be equal to one of the allowed values: PENDING, ACCEPTED, REJECTED, PRINTED, ENCLOSED, CANCELLED, DISPATCHED, DELIVERED, FAILED, RETURNED, DESTROYED, FORWARDED', + message: 'should be equal to one of the allowed values: PENDING, ACCEPTED, REJECTED, PRINTED, ENCLOSED, CANCELLED, DISPATCHED, DELIVERED, FAILED, RETURNED, FORWARDED', errorCode: 'enum.openapi.validation' }] }, From 15bbaffc203552308bc7ba8a371b7407b23a96f7 Mon Sep 17 00:00:00 2001 From: David Wass Date: Tue, 4 Nov 2025 15:28:07 +0000 Subject: [PATCH 4/4] Update endpoint statuses and patch returns 202 --- sandbox/services/LetterService.js | 41 +++++++++++++------ sandbox/utils/ResponseProvider.js | 20 ++++----- .../components/documentation/patchLetter.md | 2 +- .../api/components/endpoints/createMI.yml | 2 - .../api/components/endpoints/listLetters.yml | 2 - .../api/components/endpoints/patchLetter.yml | 4 +- .../api/components/endpoints/postLetters.yml | 4 +- .../components/responses/patchLetter200.yml | 14 ------- .../components/responses/patchLetter202.yml | 6 +++ 9 files changed, 50 insertions(+), 45 deletions(-) delete mode 100644 specification/api/components/responses/patchLetter200.yml create mode 100644 specification/api/components/responses/patchLetter202.yml diff --git a/sandbox/services/LetterService.js b/sandbox/services/LetterService.js index 1d333aa3..609c5a2f 100644 --- a/sandbox/services/LetterService.js +++ b/sandbox/services/LetterService.js @@ -82,15 +82,21 @@ const patchLetter = ({ xRequestId, id, body, xCorrelationId }) => new Promise( async (resolve, reject) => { try { const responseData = await ResponseProvider.patchLetterResponse(body); - const content = await fs.readFile(responseData.responsePath); - const fileData = JSON.parse(content); - + if (responseData.responseCode !== 202) { + const content = await fs.readFile(responseData.responsePath); + const fileData = JSON.parse(content); - resolve(Service.successResponse({ - xRequestId, - xCorrelationId, - data: fileData, - }, responseData.responseCode)); + resolve(Service.successResponse({ + xRequestId, + xCorrelationId, + data: fileData, + }, responseData.responseCode)); + } else { + resolve(Service.successResponse({ + xRequestId, + xCorrelationId, + }, responseData.responseCode)); + } } catch (e) { reject(Service.rejectResponse( e.message || 'Invalid input', @@ -112,10 +118,21 @@ const postLetters = ({ xRequestId, body, xCorrelationId }) => new Promise( const responseData = await ResponseProvider.postLettersResponse(body); try { - resolve(Service.successResponse({ - xRequestId, - xCorrelationId - }, responseData.responseCode)); + if (responseData.responseCode !== 202) { + const content = await fs.readFile(responseData.responsePath); + const fileData = JSON.parse(content); + + resolve(Service.successResponse({ + xRequestId, + xCorrelationId, + data: fileData, + }, responseData.responseCode)); + } else { + resolve(Service.successResponse({ + xRequestId, + xCorrelationId, + }, responseData.responseCode)); + } } catch (e) { reject(Service.rejectResponse( e.message || 'Invalid input', diff --git a/sandbox/utils/ResponseProvider.js b/sandbox/utils/ResponseProvider.js index ae6e69e0..1e091637 100644 --- a/sandbox/utils/ResponseProvider.js +++ b/sandbox/utils/ResponseProvider.js @@ -76,16 +76,16 @@ async function getLettersResponse(limit) { async function patchLetterResponse(request) { const patchLetterFileMap = { - 'data/examples/patchLetter/requests/patchLetter_PENDING.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_PENDING.json',responseCode: 200}, - 'data/examples/patchLetter/requests/patchLetter_ACCEPTED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_ACCEPTED.json',responseCode: 200}, - 'data/examples/patchLetter/requests/patchLetter_REJECTED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_REJECTED.json',responseCode: 200}, - 'data/examples/patchLetter/requests/patchLetter_PRINTED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_PRINTED.json',responseCode: 200}, - 'data/examples/patchLetter/requests/patchLetter_ENCLOSED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_ENCLOSED.json',responseCode: 200}, - 'data/examples/patchLetter/requests/patchLetter_CANCELLED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_CANCELLED.json',responseCode: 200}, - 'data/examples/patchLetter/requests/patchLetter_DISPATCHED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_DISPATCHED.json',responseCode: 200}, - 'data/examples/patchLetter/requests/patchLetter_DELIVERED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_DELIVERED.json',responseCode: 200}, - 'data/examples/patchLetter/requests/patchLetter_FAILED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_FAILED.json',responseCode: 200}, - 'data/examples/patchLetter/requests/patchLetter_RETURNED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_RETURNED.json',responseCode: 200}, + 'data/examples/patchLetter/requests/patchLetter_PENDING.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_PENDING.json',responseCode: 202}, + 'data/examples/patchLetter/requests/patchLetter_ACCEPTED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_ACCEPTED.json',responseCode: 202}, + 'data/examples/patchLetter/requests/patchLetter_REJECTED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_REJECTED.json',responseCode: 202}, + 'data/examples/patchLetter/requests/patchLetter_PRINTED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_PRINTED.json',responseCode: 202}, + 'data/examples/patchLetter/requests/patchLetter_ENCLOSED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_ENCLOSED.json',responseCode: 202}, + 'data/examples/patchLetter/requests/patchLetter_CANCELLED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_CANCELLED.json',responseCode: 202}, + 'data/examples/patchLetter/requests/patchLetter_DISPATCHED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_DISPATCHED.json',responseCode: 202}, + 'data/examples/patchLetter/requests/patchLetter_DELIVERED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_DELIVERED.json',responseCode: 202}, + 'data/examples/patchLetter/requests/patchLetter_FAILED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_FAILED.json',responseCode: 202}, + 'data/examples/patchLetter/requests/patchLetter_RETURNED.json': {responsePath:'data/examples/patchLetter/responses/patchLetter_RETURNED.json',responseCode: 202}, 'data/examples/patchLetter/requests/patchLetter_INVALID.json': {responsePath:'data/examples/errors/responses/badRequest.json',responseCode: 400}, 'data/examples/patchLetter/requests/patchLetter_NOTFOUND.json': {responsePath:'data/examples/errors/responses/resourceNotFound.json',responseCode: 404}, }; diff --git a/specification/api/components/documentation/patchLetter.md b/specification/api/components/documentation/patchLetter.md index ad4dc3cb..4958c9fd 100644 --- a/specification/api/components/documentation/patchLetter.md +++ b/specification/api/components/documentation/patchLetter.md @@ -2,7 +2,7 @@ Use this endpoint to update the status of a letter by submitting the new status in the request body, optionally providing a reason code and text. -When you make a PATCH request with your application, the endpoint will respond with a successful (200) response code, along with the updated patient resource or an unsuccessful (4xx/5xx) response. +When you make a PATCH request with your application, the endpoint will respond with an accepted (202) response code 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. diff --git a/specification/api/components/endpoints/createMI.yml b/specification/api/components/endpoints/createMI.yml index 09d0ebce..04ee8664 100644 --- a/specification/api/components/endpoints/createMI.yml +++ b/specification/api/components/endpoints/createMI.yml @@ -11,8 +11,6 @@ responses: $ref: "../responses/postMI201.yml" '400': $ref: "../responses/errors/badRequest.yml" - '404': - $ref: "../responses/errors/resourceNotFound.yml" '429': $ref: "../responses/errors/tooManyRequests.yml" '500': diff --git a/specification/api/components/endpoints/listLetters.yml b/specification/api/components/endpoints/listLetters.yml index ab877e52..2d300c65 100644 --- a/specification/api/components/endpoints/listLetters.yml +++ b/specification/api/components/endpoints/listLetters.yml @@ -14,8 +14,6 @@ responses: $ref: "../responses/getLetters200.yml" '400': $ref: "../responses/errors/listLetters/listLettersBadRequest.yml" - '404': - $ref: "../responses/errors/resourceNotFound.yml" '429': $ref: "../responses/errors/tooManyRequests.yml" '500': diff --git a/specification/api/components/endpoints/patchLetter.yml b/specification/api/components/endpoints/patchLetter.yml index a6e9cff5..7e8775e2 100644 --- a/specification/api/components/endpoints/patchLetter.yml +++ b/specification/api/components/endpoints/patchLetter.yml @@ -5,8 +5,8 @@ description: requestBody: $ref: "../requests/patchLetterRequest.yml" responses: - "200": - $ref: "../responses/patchLetter200.yml" + "202": + $ref: "../responses/patchLetter202.yml" "400": $ref: "../responses/errors/patchLetter/patchLetterBadRequest.yml" "404": diff --git a/specification/api/components/endpoints/postLetters.yml b/specification/api/components/endpoints/postLetters.yml index 54c5faba..4aeee72a 100644 --- a/specification/api/components/endpoints/postLetters.yml +++ b/specification/api/components/endpoints/postLetters.yml @@ -9,8 +9,8 @@ requestBody: responses: '202': $ref: "../responses/postLetters202.yml" - '404': - $ref: "../responses/errors/resourceNotFound.yml" + '400': + $ref: "../responses/errors/badRequest.yml" '429': $ref: "../responses/errors/tooManyRequests.yml" '500': diff --git a/specification/api/components/responses/patchLetter200.yml b/specification/api/components/responses/patchLetter200.yml deleted file mode 100644 index 2f7d79c6..00000000 --- a/specification/api/components/responses/patchLetter200.yml +++ /dev/null @@ -1,14 +0,0 @@ -description: Letter resource updated successfully -headers: - X-Request-ID: - $ref: "../responseHeaders/xRequestId.yml" - X-Correlation-ID: - $ref: "../responseHeaders/xCorrelationId.yml" -content: - application/vnd.api+json: - schema: - $ref: "../schemas/letterStatusData.yml" - examples: - patch_letter-response: - value: - $ref: ../examples/patchLetter/responses/patchLetter_ACCEPTED.json diff --git a/specification/api/components/responses/patchLetter202.yml b/specification/api/components/responses/patchLetter202.yml new file mode 100644 index 00000000..37447b5a --- /dev/null +++ b/specification/api/components/responses/patchLetter202.yml @@ -0,0 +1,6 @@ +description: 202 (Accepted) Acknowledges Letter resource update has been received +headers: + X-Request-ID: + $ref: "../responseHeaders/xRequestId.yml" + X-Correlation-ID: + $ref: "../responseHeaders/xCorrelationId.yml"