Skip to content

Commit

Permalink
Add the specification and update Makefile
Browse files Browse the repository at this point in the history
  • Loading branch information
@kris-szlapa
kris-szlapa committed Sep 11, 2024
1 parent 8849c9d commit 3453cf3
Show file tree
Hide file tree
Showing 6 changed files with 423 additions and 2 deletions.
10 changes: 8 additions & 2 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,10 @@ sam-deploy-package: guard-artifact_bucket guard-artifact_bucket_prefix guard-sta
compile-node:
npx tsc --build tsconfig.build.json

compile: compile-node
compile-specification:
npm run resolve --workspace packages/specification/

compile: compile-node compile-specification

download-get-secrets-layer:
mkdir -p packages/getSecretLayer/lib
Expand All @@ -112,6 +115,9 @@ lint-node: compile-node
npm run lint --workspace packages/statusLambda
npm run lint --workspace packages/common/testing

lint-specification: compile-specification
npm run lint --workspace packages/specification

lint-samtemplates:
poetry run cfn-lint -I "SAMtemplates/**/*.y*ml" 2>&1 | awk '/Run scan/ { print } /^[EW][0-9]/ { print; getline; print }'

Expand All @@ -124,7 +130,7 @@ lint-githubactions:
lint-githubaction-scripts:
shellcheck .github/scripts/*.sh

lint: lint-node lint-samtemplates lint-python lint-githubactions lint-githubaction-scripts
lint: lint-node lint-samtemplates lint-python lint-githubactions lint-githubaction-scripts lint-specification

test: compile
npm run test --workspace packages/sandbox
Expand Down
260 changes: 260 additions & 0 deletions packages/specification/eps-clinical-prescription-tracker.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,260 @@
# This is an OpenAPI Specification (https://swagger.io/specification/)
# for the Clinical Prescription Tracker API
# owned by NHS Digital (https://digital.nhs.uk/)

openapi: 3.0.3
info:
title: Clinical Prescription Tracker API
version: "0.0.1"
contact:
name: Clinical Prescription Tracker API Support
url: https://digital.nhs.uk/developer/help-and-support
email: [email protected]
description: |
## Overview
The Clinical Prescription Tracker API
## Who can use this API
The Clinical Prescription Tracker query API is intended for NHS England internal use only.
## Related APIs
* [Electronic Prescriptions Service](https://digital.nhs.uk/developer/api-catalogue/electronic-prescription-service-fhir): The national service for creating and dispensing prescriptions across health and social care.
* [Prescriptions for Patients](https://digital.nhs.uk/developer/api-catalogue/prescriptions-for-patients): 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 will be a platinum service, meaning it is operational and supported 24 hours a day, 365 days a year.
See [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels) for more details.
## Technology
This API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).
It conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir) global standard for health care data exchange, specifically to [FHIR R4 (v4.0.1)](https://hl7.org/fhir/r4/).
It includes some country-specific FHIR extensions, which are built against FHIR UK Core, specifically [UK Core R4 (v4.0.1)](https://simplifier.net/HL7FHIRUKCoreR4/).
You do not need to know much about FHIR to use this API. The API only supports POST requests containing FHIR messages.
FHIR APIs are just RESTful APIs that follow specific rules.
These rules mean:
* resource names are capitalised and singular, for example `/Bundle` not `/bundle`
* array names are singular, for example `line` not `lines` for address lines
* data items that are country specific and not included in the FHIR global base resources are usually wrapped in an `extension` object
There are [libraries and software development kits](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) available to help with FHIR API integration.
## 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, meaning we authenticate the calling application but not the end user.
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 integrated with a shipping system
To use this access mode, 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)
## Environment and testing
| Environment | Base URL |
|------------------|---------------------------------------------------------------------|
| Sandbox | `https://sandbox.api.service.nhs.uk/clinical-prescription-tracker` |
| Integration test | `https://int.api.service.nhs.uk/clinical-prescription-tracker` |
| Production | `https://api.service.nhs.uk/clinical-prescription-tracker` |
### 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.
## 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.
x-spec-publication:
operation-order:
- operations:
- method: GET
path: /

servers:
- url: "https://sandbox.api.service.nhs.uk/clinical-prescription-tracker"
description: Sandbox
- url: "https://int.api.service.nhs.uk/clinical-prescription-tracker"
description: Integration
- url: "https://api.service.nhs.uk/clinical-prescription-tracker"
description: Production

paths:
/:
get:
operationId: clinical-prescription-tracker-bundle
summary: Get prescriptions
description: |
## Overview
Use this endpoint to search for EPS prescriptions and find out what the status of the prescription is.
parameters:
- $ref: "#/components/parameters/BearerAuthorisation"
- $ref: "#/components/parameters/RequestID"
- $ref: "#/components/parameters/CorrelationID"
responses:
"200":
description: Successful retrieval.
content:
application/fhir+json:
schema:
$ref: "#/components/schemas/ResponseBundle"
"4XX":
description: |
An error occurred as follows:
| HTTP status | Error code | Description |
| ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | `value` | Missing values or invalid JSON in request |
| 401 | `processing` | Missing or invalid OAuth 2.0 bearer token in request |
| 408 | `timeout` | Request timed out |
The error code will be included in the returned OperationOutcome (below).
content:
application/fhir+json:
schema:
$ref: "#/components/schemas/OperationOutcome"
security:
- app-level0: []
components:
securitySchemes:
app-level0:
$ref: https://proxygen.ptl.api.platform.nhs.uk/components/securitySchemes/app-level0
parameters:
BearerAuthorisation:
in: header
name: Authorization
description: |
An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis).
required: true
schema:
type: string
format: '^Bearer\ [[:ascii:]]+$'
example: "Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"
RequestID:
in: header
name: X-Request-ID
required: true
description: |
A globally unique identifier (GUID) for the request, which we use to correlate logs through different components.
Must be a universally unique identifier (UUID) (ideally version 4).
Mirrored back in a response header.
schema:
type: string
pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
example: 60E0B220-8136-4CA5-AE46-1D97EF59D068
CorrelationID:
in: header
name: X-Correlation-ID
required: false
description: |
An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding `.` characters.
Mirrored back in a response header.
schema:
type: string
example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
schemas:
ResponseBundle:
type: object
required: [resourceType, type, entry]
description: A FHIR searchset Bundle.
properties:
resourceType:
type: string
enum: [Bundle]
description: FHIR resource type.
id:
type: string
description: Object ID for the Bundle.
example: 164996aa-29eb-4f14-a5ac-4b556a7baf6e
meta:
type: object
description: Metadata about the bundle
type:
type: string
description: Denotes that the bundle is a list of resources returned as a result of a search.
enum: [searchset]
total:
type: number
description: |
The number of prescription bundles contained within the searchset
Note that this excludes OperationOutcomes.
entry:
type: array
description: |
A collection of resources contained within the Bundle.
Note that the presence of an OperationOutcome resource as part of the bundle implies that one
of a patient's prescriptions have been excluded from the response due to a processing error.
An OperationOutcome resource will be included for each prescription that cannot be processed.
items:
oneOf:
- $ref: "#/components/schemas/PrescriptionBundle"
- $ref: "#/components/schemas/OperationOutcome"
PrescriptionBundle:
type: object
required:
- fullUrl
- search
- resource
properties:
fullUrl:
type: string
example: urn:uuid:fedef61e-bc62-452e-91c0-6f44ad2d5c0c
description: The FHIR urn of the contained Bundle
search:
type: object
properties:
mode:
type: string
example: match
OperationOutcome:
$ref: schemas/resources/OperationOutcome.yaml
x-nhsd-apim:
temporary: false
monitoring: false
access:
- title: Application Restricted
grants:
app-level0: []
target:
type: hosted
healthcheck: /_status
url: https://clinical-tracker.dev.eps.national.nhs.uk
security:
type: mtls
secret: clinical-tracker-mtls-1
22 changes: 22 additions & 0 deletions packages/specification/package.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
{
"name": "apim-spec",
"version": "0.0.1",
"description": "OAS (Swagger v3) API Definition for Electronic Prescription Service Prescription Clinical Tracker",
"type": "module",
"scripts": {
"lint": "redocly lint --extends=recommended --config ./redocly.yaml",
"resolve": "redocly bundle eps-clinical-prescription-tracker.yaml -d -o dist/eps-clinical-prescription-tracker.resolved.json",
"clean": "rm -rf lib coverage",
"check-licenses": "license-checker --failOn GPL --failOn LGPL --start ../.."
},
"author": "NHS Digital",
"license": "MIT",
"engines": {
"node": "20.10.x",
"npm": "10.2.x"
},
"homepage": "https://github.com/NHSDigital/electronic-prescription-service-clinical-prescription-tracker",
"devDependencies": {
"@redocly/cli": "^1.24.0"
}
}
3 changes: 3 additions & 0 deletions packages/specification/redocly.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
apis:
cpts:
root: ./dist/eps-clinical-prescription-tracker.resolved.json
16 changes: 16 additions & 0 deletions packages/specification/schemas/fragments/codes.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
SpineErrorOrWarningCode:
type: object
required: [system, code]
properties:
system:
type: string
description: URI of the coding system specification.
enum: [https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode]
code:
type: string
description: Symbol in syntax defined by the system.
example: INVALID_VALUE
display:
type: string
description: Representation defined by the system.
example: Provided value is invalid
Loading

0 comments on commit 3453cf3

Please sign in to comment.