Skip to content

Commit 8a3fd76

Browse files
nhsd-david-wassnhsd-david-wass
committed
Initial Descriptions and ptl config
1 parent d25a78d commit 8a3fd76

29 files changed

+178
-27
lines changed

‎scripts/config/markdownlint.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,6 @@ MD024:
99

1010
# https://github.com/DavidAnson/markdownlint/blob/main/doc/md033.md
1111
MD033: false
12+
13+
MD041:
14+
level: 2

‎specification/api/components/documentation/APIDescription.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
## Overview
2+
3+
API for communication suppliers to integrate with NHS Notify.
4+
5+
This specification represents the in-development 'next' version of the API schema
6+
and should be treated as unstable
7+
8+
Use this API to retrieve letters to be printed
9+
10+
## Who can use this API
11+
12+
The NHS Notify Supplier service is intended for suppliers of print services to the [NHS Notify](https://digital.nhs.uk/services/nhs-notify) service
13+
14+
## Related APIs
15+
16+
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.
17+
18+
## API status and roadmap
19+
20+
This API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses) meaning:
21+
22+
* it is available for testing in the integration environment
23+
* we expect to make breaking changes based on developer feedback
24+
25+
## Service Level
26+
27+
TBD
28+
29+
For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).
30+
31+
## Technology
32+
33+
This API is a [REST-based](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest) API.
34+
35+
We follow the [JSON:API](https://jsonapi.org/) standard for our request and response schemas.
36+
37+
### Response content types
38+
39+
This API can generate responses in the following formats:
40+
41+
* `application/vnd.api+json` - see [JSON:API specification](https://jsonapi.org/format/#introduction)
42+
43+
## Network access
44+
45+
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).
46+
47+
For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).
48+
49+
## Security and authorisation
50+
51+
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.
52+
53+
Authentication and authorisation of end users is the responsibility of your application.
54+
55+
To access this API, use the following security pattern:
56+
57+
* [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)
58+
59+
## Environments and testing
60+
61+
| Environment | Base URL |
62+
|------------ | -------- |
63+
| Sandbox | `https://sandbox.api.service.nhs.uk/comms` |
64+
| Integration test | `https://int.api.service.nhs.uk/comms` |
65+
| Production | `https://api.service.nhs.uk/comms` |
66+
67+
### Sandbox testing
68+
69+
Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing):
70+
71+
* is for early developer testing
72+
* only covers a limited set of scenarios
73+
* is stateless, so does not actually persist any updates
74+
* is open access, so does not allow you to test authorisation
75+
76+
For details of sandbox test scenarios, or to try out sandbox using our 'Try this API' feature, see the documentation for each endpoint.
77+
78+
### Integration testing
79+
80+
Our integration test environment:
81+
82+
* is for formal integration sandbox-testing
83+
* is stateful, so persists updates
84+
* includes authorisation via [signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)
85+
86+
You need to get your software approved by us before it can go live with this API.
87+
88+
You will also need to follow our steps to - TBD

‎specification/api/components/documentation/createMI.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## Overview
2+
3+
Use this endpoint to create management information

‎specification/api/components/documentation/getDataId.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## Overview
2+
3+
Use this endpoint to get letter data

‎specification/api/components/documentation/getLetterStatus.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
## Overview
2+
3+
Use this endpoint to get details the status of a letter.
4+
5+
## Sandbox test scenarios
6+
7+
You can test the following scenarios in our sandbox environment
8+
9+
| Scenario | Letter Id |
10+
| ----------------------------------------| ---------------------------- |
11+
| Retrieve a PENDING letter status | `24L5eYSWGzCHlGmzNxuqVusPxDg`|
12+
| Retrieve a ACCEPTED letter status | `2AL5eYSWGzCHlGmzNxuqVusPxDg`|
13+
| Retrieve a PRINTED letter status | `2BL5eYSWGzCHlGmzNxuqVusPxDg`|
14+
| Retrieve a ENCLOSED letter status | `2CL5eYSWGzCHlGmzNxuqVusPxDg`|
15+
| Retrieve a DISPATCHED letter status | `2DL5eYSWGzCHlGmzNxuqVusPxDg`|
16+
| Retrieve a DELIVERED letter status | `2EL5eYSWGzCHlGmzNxuqVusPxDg`|
17+
| Retrieve a REJECTED letter status | `2WL5eYSWGzCHlGmzNxuqVusPxDg`|
18+
| Retrieve a CANCELLED letter status | `2XL5eYSWGzCHlGmzNxuqVusPxDg`|
19+
| Retrieve a FAILED letter status | `2YL5eYSWGzCHlGmzNxuqVusPxDg`|
20+
| Retrieve a RETURNED letter status | `2ZL5eYSWGzCHlGmzNxuqVusPxDg`|

‎specification/api/components/documentation/headDataId.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## Overview
2+
3+
Use this endpoint to check for the existence of letter data

‎specification/api/components/documentation/listLetters.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## Overview
2+
3+
The key use of this endpoint is to query letters which are ready to be printed

‎specification/api/components/documentation/patchLetters.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## Overview
2+
3+
Update the status of a letter by providing the new status in the request body.

‎specification/api/components/documentation/postLetters.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## Overview
2+
3+
Update the status of multiple letters by providing the new statuses in the request body.

‎specification/api/components/endpoints/createMI.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
summary: Create a new MI record
2+
description:
3+
$ref: '../documentation/createMI.md'
24
operationId: createMI
35
tags:
46
- mi

0 commit comments

Comments
 (0)