eps-prescription-status-update-api/packages/specification/eps-custom-prescription-status-update-api.yaml at 44d33b4f2970ae539b5ab398baf15792079425aa · NHSDigital/eps-prescription-status-update-api · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
# This is an OpenAPI Specification (https://swagger.io/specification/)
# for the Prescription Status Update API
# owned by NHS Digital (https://digital.nhs.uk/)

openapi: 3.0.3
info:
  title: Custom Prescription Status Update API
  version: "0.0.1"
  contact:
    name: Custom Prescription Status Update API Support
    url: https://digital.nhs.uk/developer/help-and-support
    email: api.management@nhs.net
  description: |
    ## Overview
    The Custom Prescription Status Update API is restricted to dispensing suppliers with an existing prescription
    status update solution, who can onboard to provide updates to patients on a national scale via the NHS App
    (and other third parties in the future) by September 2024.

    You can:
    * enable patients to know when their prescription is ready
    * enable dispensing suppliers to push status information about electronic prescriptions
    ## Who can use this API
    The Custom Prescription Status Update API is intended for those dispensing suppliers who have signed the MOU to
    supply status updates by September 2024, so they can provide and push the information required to a central NHS data store.
    ## Related APIs
    The following APIs are related to the "Custom Prescription Status Update" API:
    * [Electronic Prescriptions Service Prescribing](https://digital.nhs.uk/developer/api-catalogue/eps-fhir-prescribing-api): the national service for creating prescriptions across health and social care.
    * [Electronic Prescriptions Service Dispensing](https://digital.nhs.uk/developer/api-catalogue/eps-fhir-dispensing-api): the national service for dispensing prescriptions across health and social care.
    * [Prescriptions for Patients](https://digital.nhs.uk/developer/api-catalogue/prescriptions-for-patients-fhir-api-v2): the national service to retrieve prescriptions data for individual patients from the Electronic Prescription Service (EPS), for use in patient-facing applications.
    ## API status and roadmap
    This API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), meaning the API will soon be available for testing via a sandbox service or an integration environment - but we expect to make breaking changes based on developer feedback.
    ## Service Level
    This API is a silver service, meaning it is operational and supported between 8am and 6pm, Monday to Friday, but not bank holidays.
    For more details see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).
    ## Technology
    This API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).
    ## Network access
    This API is available on the internet.
    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 only supports [application-restricted access](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-api-key-authentication), meaning we authenticate the calling application but not the end user.
    ### Application-restricted Access
    The end user could be:
    * a healthcare worker - in which case you must ensure they are authenticated and suitably authorised locally
    * not present at all - for example as part of a back end process to check NHS numbers for data flowing from one system to another
    ### Errors
    We use standard HTTP status codes to show whether an API request succeeded or not.
    They are usually in the range:
    * 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
    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.
     ## 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 |
    |----------|-------------|-------|
    | FHIR libraries and SDKs | Various open source libraries for integrating with FHIR APIs. | [FHIR libraries and SDKs](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) |
    | nhs-number | Python package containing utilities for NHS numbers including validity checks, normalisation and generation. | [GitHub repo](https://github.com/uk-fci/nhs-number) \| [Python Package index](https://pypi.org/project/nhs-number/) \| [Docs](https://nhs-number.uk-fci.tech/) |
    | Prescription Status Update API | Source code for the EPS Prescription Status Update API | [GitHub](https://github.com/NHSDigital/eps-prescription-status-update-api) |
    | EPS FHIR Validator Lambda | An AWS Lambda function that validates FHIR R4 messages | [GitHub](https://github.com/NHSDigital/eps-FHIR-validator-lambda) |
    ## Environment and testing
    | Environment      | Base URL                                                                   |
    |------------------|----------------------------------------------------------------------------|
    | Sandbox          | `https://sandbox.api.service.nhs.uk/custom-prescription-status-update`     |
    | Integration test | `https://int.api.service.nhs.uk/custom-prescription-status-update`         |
    | Production       | `https://api.service.nhs.uk/custom-prescription-status-update`             |
    ### 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 it does not actually persist any updates
    * is open access, so does not allow you to test authorisation
    For details of sandbox testing, or to try out the sandbox using our "Try this API" feature, see the documentation for each endpoint.
    ### Integration testing
    Our [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):
    * is for formal integration testing
    * is stateful, so persists updates
    * includes authorisation, with [smartcard](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/nhs-smartcards-for-developers) and non-smartcard options
    For more details see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis).
    ## Onboarding
    All dispenser suppliers are being asked to integrate with this new service.

servers:
  - url: https://sandbox.api.service.nhs.uk/custom-prescription-status-update
    description: Sandbox
  - url: https://int.api.service.nhs.uk/custom-prescription-status-update
    description: Integration
  - url: https://api.service.nhs.uk/custom-prescription-status-update
    description: Production

paths:
  /format-1:
    post:
      operationId: format-1-prescription-status-update
      summary: Format 1 update prescription status
      description: |
        ## Overview
        Status updates will be provided on prescription items to allow users of the NHS App and third-party app consumers to track the progress of their prescriptions and when ready to collect.
      parameters:
        - $ref: "#/components/parameters/ApiKey"
      requestBody:
        required: true
        content:
          application/json:
            examples:
              multiple-items:
                summary: multiple-items
                description: A request message contains multiple items.
                value:
                  $ref: "examples/format-1-request-multiple-items.json"
      responses:
        "2XX":
          description: |
            The request was processed successfully. Below are the possible status codes within the 2XX range that may be returned:
            | HTTP status | Status code     | Description                                                                                                 |
            | ----------- | --------------- | ----------------------------------------------------------------------------------------------------------- |
            | 200         | `success`       | The request was successfully processed.                                                                     |
            | 201         | `success`       | A new resource was successfully created. No issues detected during validation.                              |
            | 202         | `informational` | The request was accepted, but no change occurred due to a duplicate update.                                 |
          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/ResponseBundle"
              examples:
                single-item:
                  description:
                    A successful response to a UpdatePrescriptionStatus request,
                    contains a single item.
                  value:
                    $ref: examples/response-single-item.json
                multiple-items:
                  description:
                    A successful response to a UpdatePrescriptionStatus request,
                    contains multiple items.
                  value:
                    $ref: examples/response-multiple-items.json
        "4XX":
          description: An error occurred.
          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              example:
                $ref: examples/error-invalid-prescriptionid.json
        "5XX":
          description: |
            An error occurred due to a server-side issue. Below are the possible status codes within the 5XX range that may be returned:
            | HTTP status | Error code      | Description                                                                                                 |
            | ----------- | --------------- | ----------------------------------------------------------------------------------------------------------- |
            | 500         | `exception`     | The server has encountered an error processing the request.                                                 |
            | 504         | `timeout`       | The server has timed out while processing the request sent by the client.                                   |
      security:
        - app-level0: []
components:
  securitySchemes:
    app-level0:
      $ref: https://proxygen.prod.api.platform.nhs.uk/components/securitySchemes/app-level0
  parameters:
    ApiKey:
      in: header
      name: API-KEY
      required: true
      description: |
        API Key used to authenticate with the system
      schema:
        type: string
        example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
  schemas:
    ResponseBundle:
      $ref: schemas/components/ResponseBundle.yaml
    OperationOutcome:
      $ref: schemas/resources/OperationOutcome.yaml
security:
  - app-level0: []
x-nhsd-apim:
  temporary: false
  monitoring: true
  access:
    - title: Application Restricted with API key
      grants:
        app-level0: []
  target:
    type: external
    healthcheck: /_status
    url: https://psu.dev.eps.national.nhs.uk
    security:
      type: mtls
      secret: psu-mtls-1
  target-attributes:
    - name: DisplayName
      required: true
      header: attribute-name
  ratelimiting:
    proxy:
      limit: 20000
      timeunit: minute
    app-default:
      limit: 20000
      timeunit: minute