Skip to content

Commit

Permalink
Docs: [AEA-4249] - PSU API OAS issues (#552)
Browse files Browse the repository at this point in the history
## Summary

🎫 [AEA-4249](https://nhsd-jira.digital.nhs.uk/browse/AEA-4249) PSU API
OAS issues

- Routine Change

### Details

PSU API OAS issues
  • Loading branch information
kris-szlapa authored Jul 29, 2024
1 parent 2a830a5 commit 881a8a5
Show file tree
Hide file tree
Showing 6 changed files with 166 additions and 90 deletions.
1 change: 1 addition & 0 deletions .vscode/eps-prescription-status-update-api.code-workspace
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,7 @@
"pollable",
"powertools",
"pratica",
"prescriptionid",
"Prosthetist",
"pylint",
"pytest",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -94,12 +94,24 @@ paths:
value:
$ref: "examples/format-1-request-multiple-items.json"
responses:
"200":
description: Successful creation.
"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 for processing. A duplicate update was detected, and the message was valid but did not result in a change. |
"4XX":
description: An error occurred.
"5XX":
description: An error occurred.
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:
Expand Down
42 changes: 25 additions & 17 deletions packages/specification/eps-prescription-status-update-api.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ info:
|----------|-------------|-------|
| 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-ap) |
| 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 |
Expand Down Expand Up @@ -126,8 +126,7 @@ paths:
$ref: examples/request-ready-to-dispatch.json
ready-to-dispatch-partial:
summary: ready-to-dispatch-partial
description:
A request message contains tracking status `Ready to Dispatch -
description: A request message contains tracking status `Ready to Dispatch -
Partial`.
value:
$ref: examples/request-ready-to-dispatch-partial.json
Expand All @@ -152,42 +151,52 @@ paths:
value:
$ref: examples/request-multiple-items.json
responses:
"200":
description: Successful retrieval.
"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. |
content:
application/fhir+json:
schema:
$ref: "#/components/schemas/ResponseBundle"
examples:
single-item:
description:
A successful response to a UpdatePrescriptionStatus request,
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,
description: A successful response to a UpdatePrescriptionStatus request,
contains multiple items.
value:
$ref: examples/response-multiple-items.json

4XX:
"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 |
| 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. |
| 409 | `duplicate` | Request contains a task ID and prescription ID identical to a record already in the data store. |
| 429 | `throttled` | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
The error code will be included in the returned OperationOutcome (below).
content:
application/fhir+json:
schema:
$ref: "#/components/schemas/OperationOutcome"
example:
$ref: examples/error-ods-code.json
$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-level3: []
/metadata:
Expand Down Expand Up @@ -330,8 +339,7 @@ components:
- Bundle
type:
type: string
description:
Denotes that the bundle is a list of status updates to be performed
description: Denotes that the bundle is a list of status updates to be performed
as one transaction.
enum:
- transaction
Expand Down
25 changes: 25 additions & 0 deletions packages/specification/examples/error-invalid-prescriptionid.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
{
"resourceType": "Bundle",
"type": "transaction-response",
"entry": [
{
"response": {
"status": "400 Bad Request",
"outcome": {
"resourceType": "OperationOutcome",
"meta": {
"lastUpdated": "2024-07-22T23:59:07.673Z"
},
"issue": [
{
"code": "value",
"severity": "error",
"diagnostics": "Prescription ID is invalid."
}
]
}
},
"fullUrl": "urn:uuid:3b2d36a9-3cff-45e4-93a7-d1f70f911496"
}
]
}
168 changes: 99 additions & 69 deletions packages/specification/schemas/resources/OperationOutcome.yaml
Original file line number Diff line number Diff line change
@@ -1,84 +1,114 @@
type: object
required: [resourceType, id, meta, issue]
required: [resourceType, type, entry]
description: |
Outcome of an operation that does not result in a resource or bundle being returned.
For example - error, async/batch submission.
properties:
resourceType:
type: string
description: FHIR Resource Type.
enum: [OperationOutcome]
id:
enum: [Bundle]
description: The type of resource.
type:
type: string
description: ID to link the request and response (Lambda request ID)
meta:
type: object
required: [lastUpdated]
description: Metadata regarding the request
properties:
lastUpdated:
type: string
description: Timestamp at which the response was generated
issue:
enum: [transaction-response]
description: The type of bundle.
entry:
type: array
description: List of issues that have occurred.
minItems: 1
description: An array of entry objects, each representing a single response in the transaction-response bundle.
items:
type: object
required: [severity, code]
required: [response, fullUrl]
properties:
severity:
type: string
enum: [fatal, error, warning, information]
description: Severity of the error.
code:
type: string
description: FHIR error code.
enum:
- business-rule
- code-invalid
- conflict
- deleted
- duplicate
- exception
- expired
- extension
- forbidden
- incomplete
- informational
- invalid
- invariant
- lock-error
- login
- multiple-matches
- no-store
- not-supported
- not-found
- processing
- required
- structure
- security
- suppressed
- throttled
- timeout
- too-costly
- too-long
- transient
- unknown
- value
details:
response:
type: object
description: Internal error code.
required: [status, outcome]
description: Contains the response details for the transaction.
properties:
coding:
type: array
items:
$ref: ../fragments/codes.yaml#/SpineErrorOrWarningCode
expression:
type: string
description: FHIR Path of element(s) related to the error.
example: Patient.name.given
diagnostics:
status:
type: string
description: HTTP status code and reason.
example: 400 Bad Request
outcome:
type: object
required: [resourceType, meta, issue]
description: Outcome details of the operation.
properties:
resourceType:
type: string
description: FHIR Resource Type.
enum: [OperationOutcome]
meta:
type: object
required: [lastUpdated]
description: Metadata regarding the request
properties:
lastUpdated:
type: string
description: Timestamp at which the response was generated
issue:
type: array
description: List of issues that have occurred.
minItems: 1
items:
type: object
required: [severity, code]
properties:
severity:
type: string
enum: [fatal, error, warning, information]
description: Severity of the error.
code:
type: string
description: FHIR error code.
enum:
- business-rule
- code-invalid
- conflict
- deleted
- duplicate
- exception
- expired
- extension
- forbidden
- incomplete
- informational
- invalid
- invariant
- lock-error
- login
- multiple-matches
- no-store
- not-supported
- not-found
- processing
- required
- structure
- security
- suppressed
- throttled
- timeout
- too-costly
- too-long
- transient
- unknown
- value
details:
type: object
description: Internal error code.
properties:
coding:
type: array
items:
$ref: ../fragments/codes.yaml#/SpineErrorOrWarningCode
expression:
type: string
description: FHIR Path of element(s) related to the error.
example: Patient.name.given
diagnostics:
type: string
description: A description of the reasoning for including an OperationOutcome
example: Prescription ID is invalid.
fullUrl:
type: string
description: A description of the reasoning for including an OperationOutcome
example: Some prescriptions have been invalidated so could not be returned.
description: A URL or UUID that identifies the full location of the resource.
example: urn:uuid:3b2d36a9-3cff-45e4-93a7-d1f70f911496
2 changes: 1 addition & 1 deletion packages/updatePrescriptionStatus/src/utils/responses.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ export function badRequest(diagnostics: string, fullUrl: string | undefined = un
},
issue: [
{
code: "processing",
code: "value",
severity: "error",
diagnostics: diagnostics
}
Expand Down

0 comments on commit 881a8a5

Please sign in to comment.