|
3 | 3 | openapi: '3.0.3' |
4 | 4 | info: |
5 | 5 | title: "Patient Care Aggregator Get Appointments, Documents and Questionnaires API Standard" |
6 | | - version: "1.0.3" |
| 6 | + version: "3.5.0" |
7 | 7 | description: | |
8 | 8 | ## Overview |
9 | 9 |  |
|
50 | 50 |
|
51 | 51 | | Requirement Reference | Quality attribute(s) | Requirement | MoSCoW | |
52 | 52 | |-----------------------|------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------| |
53 | | - | WF-NFR-01 | Performance | **Response times**<br>Each API (including Appointment, Document, and Questionnaire) must respond with patient data within 400ms 95th percentile (P95).<br>Page load times during the deeplink jump-off and after the blue screen hand-off between the NHS App and a Portal system, should not exceed 3 seconds, as perceived by the end-user. The hand-off involves multiple message exchanges between NHS App, NHS login and the Portal system. The aggregate NHS App and NHS login response time is 1 second (at 95th percentile) in the production environment. This means that the aggregate Portal systems' response time must be 2 seconds or less (as measured in the Portal system's volume & performance test environment, at 95th percentile). The measurements must be carried out from a browser with a strong and stable network connection. | M/S | |
| 53 | + | WF-NFR-01 | Performance | **Response times**<br>Each API (including Appointment, Document, and Questionnaire) must respond with patient data within 400ms 95th percentile (P95).<br>Page load times during the deep link jump-off and after the blue screen hand-off between the NHS App and a Portal system, should not exceed 3 seconds, as perceived by the end-user. The hand-off involves multiple message exchanges between NHS App, NHS login and the Portal system. The aggregate NHS App and NHS login response time is 1 second (at 95th percentile) in the production environment. This means that the aggregate Portal systems' response time must be 2 seconds or less (as measured in the Portal system's volume & performance test environment, at 95th percentile). The measurements must be carried out from a browser with a strong and stable network connection. | M/S | |
54 | 54 | | WF-NFR-02 | Performance | **Timeouts**<br>Each API (including Appointment, Document, and Questionnaire) must respond with a HTTP 504 'Gateway Timeout' after 9,000 ms have expired. | M | |
55 | 55 | | WF-NFR-03 | Availability | **Throttling**<br>Each API must limit requests and respond with a HTTP 429 'Too Many Requests' response at 25 TPS (transactions per second) | M | |
56 | 56 | | WF-NFR-04 | Reliability | **Data timeliness**<br>Any changes made by patients within a PEP must be reflected in any subsequent request by the Patient Care Aggregator within 3 seconds (e.g. the requested appointment status if a request for a cancellation or amendment has been is made).<br>Any changes made at source (e.g. within the providers PAS) must be reflected in any subsequent request by the Patient Care Aggregator within 3 minutes. This should be sent prior to any notification regarding the update (e.g. a cancellation notification following a clinic cancellation). | M | |
|
60 | 60 | | WF-NFR-08 | Usability | **Partial response**<br>N/A | M | |
61 | 61 | | WF-NFR-09 | Observability<br>Security<br>Information governance | **Logging and alerting**<br>All Aggregator requests to Portal systems must be included into existing logging and monitoring solutions.<br>Requests from Portal systems to the Aggregator must be distinct from other log events<br>Errors must generate alarms against existing Portal system thresholds.<br>Clinical and personal identifiable data must be omitted from production logs.<br>All transactional log events that contain X-Correlation-ID must be retained for 90 days | M | |
62 | 62 | | WF-NFR-10 | Testability | **Contract testing**<br>Contract tests for endpoints used by the Aggregator must be included in the build pipeline to prevent any changes made by the Portal system that would prevent the Aggregator from functioning correctly<br>Contract tests for endpoints provided by the Aggregator must be included in the build pipeline to prevent any changes made by the Aggregator that would prevent the Portal systems from functioning correctly<br>Contract tests for endpoints provided by the NHS App's Notifications & Messaging (N&M) must be included in the build pipeline to prevent any changes made by N&M that would prevent the Portal system from functioning correctly | M | |
63 | | - | WF-NFR-11 | Performance | **Volumetrics**<br>Close tracking of the following is required for BETA period:<br>- New user sign-ups via NHS Login<br>- Number of deeplink interactions (launches from NHS App directly into appointment page)<br>- Errors (by type) | M | |
| 63 | + | WF-NFR-11 | Performance | **Volumetrics**<br>Close tracking of the following is required for BETA period:<br>- New user sign-ups via NHS Login<br>- Number of deep link interactions (launches from NHS App directly into appointment page)<br>- Errors (by type) | M | |
64 | 64 | | WF-NFR-12 | Cost<br>Security<br>Interoperability | **Hosting**<br>Portals must continue to be hosted independently. <br><br>Access to patient data must be over secure Internet using FHIR-based APIs. | M | |
65 | 65 | | WF-NFR-13 | Serviceability | **Operations**<br>Commitment of operational response against Silver+ (99.5%) availability under NHS guidelines.<br>See [Cloud security - good practice guide](https://digital.nhs.uk/services/cloud-centre-of-excellence/cloud-security-good-practice-guide/9.-appendix-b-service-classifications)<br>This will require on-call DevOps escalation for outages | M | |
66 | 66 | | WF-NFR-14 | Security | **Authentication**<br>**Patient authentication**<br>- Portal systems must be certified to use NHS login<br>- Portal systems will carry out a demographic cross-check between the NHS number passed in the API request and 'Date of Birth' from the ID token, at a minimum, before returning patient data.<br><br>**System authentication**<br>- All incoming/outgoing API calls into/from Portal systems must utilise OAuth 2.0 Client Credentials Flow pattern for system-to-system authentication.<br>- All API keys used by Portal systems must be rotated at regular intervals no more than 90 days apart, and also rotated immediately whenever there is suspicion that a key may have been compromised | M | |
|
88 | 88 |
|
89 | 89 | ## Onboarding |
90 | 90 | To onboard to this API standard, see [Integrating a secondary care booking system (onboarding section)](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/referrals-and-bookings/patient-care-aggregator/integrating-a-secondary-care-booking-system#5-complete-onboarding). |
| 91 | +
|
| 92 | + ## Patient Care Aggregator Reporting Service API considerations |
| 93 | + For Portal systems using the MIv2 specification for sending Wayfinder-related events to the [Wayfinder Reporting Service](https://digital.nhs.uk/developer/api-catalogue/patient-care-aggregator-reporting) - you will need to provide tracking information in the deep link jumpoff URL. |
| 94 | +
|
| 95 | + There are two types of patient journeys which can lead to the jumpoff in a Portal: |
| 96 | + - Wayfinder page journey - where the citizen clicks on a deep link on a Wayfinder page. |
| 97 | + The Portal system must use the **x-correlation-id** value for the tracking id parameter. This is provided in the x-correlation-id HTTP header field received in the API request from the Patient Care Aggregator. |
| 98 | +
|
| 99 | + - In-app message journey - where the citizen clicks on a deep link provided in an in-app message. |
| 100 | + The Portal system must **create and use a unique value (such as a GUID)** for the tracking id parameter. |
| 101 | +
|
| 102 | + The Portal system is responsible for adding the **extSystemName** and the **trackingid** parameters and their values to the deep link jumpoff URL where: |
| 103 | + - the value of **extSystemName** is the descriptive name of the Portal system. |
| 104 | + - the value of **trackingid** is the tracking id dependent on the type of patient journey as described above. |
| 105 | +
|
| 106 | + The format of the deep link URI becomes:<br> |
| 107 | + \<baseurl>/<relative-path>?<portal-specific-query-string>&extSystemName=<sys-name>&trackingId=<tracking-id>&assertedLoginIdentity=<sso-jwt> |
| 108 | +
|
91 | 109 | contact: |
92 | 110 | name: 'patient-care-aggregator-api API Support' |
93 | 111 | url: 'https://digital.nhs.uk/developer/help-and-support' |
@@ -421,7 +439,7 @@ components: |
421 | 439 | - "https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link" |
422 | 440 | valueUrl: |
423 | 441 | type: string |
424 | | - description: The deep link URL itself. |
| 442 | + description: The Portal provider deep link URL. Please note: If the provider is sending MI events to the Wayfinder Reporting Service API then the tracking id may need to be appended to the deep link URL. Refer to guidance at the beginning of the specification - Patient Care Aggregator Reporting Service API considerations. |
425 | 443 | example: "https://wayfinder.example-pep.com/fhir/Appointment/770DA42C-C8F2-A5F7-6185-40EE9409B494" |
426 | 444 | identifier: |
427 | 445 | type: array |
@@ -1037,7 +1055,7 @@ components: |
1037 | 1055 | - "application/pdf" |
1038 | 1056 | url: |
1039 | 1057 | type: string |
1040 | | - description: Portal provider deeplink URL |
| 1058 | + description: The Portal provider deep link URL. Please note: If the provider is sending MI events to the Wayfinder Reporting Service API then the tracking id may need to be appended to the deep link URL. Refer to guidance at the beginning of the specification - Patient Care Aggregator Reporting Service API considerations. |
1041 | 1059 | example: "https://my.portal.com/Document/b710e648-c12e-4f66-80e2-9957a254900f" |
1042 | 1060 | Task: |
1043 | 1061 | description: "FHIR TASK resource for the questionnaire" |
@@ -1189,7 +1207,7 @@ components: |
1189 | 1207 | - "Questionnaire" |
1190 | 1208 | reference: |
1191 | 1209 | type: string |
1192 | | - description: Portal provider URL of the Questionnaire being answered |
| 1210 | + description: The Portal provider deep link URL. Please note: If the provider is sending MI events to the Wayfinder Reporting Service API then the tracking id may need to be appended to the deep link URL. Refer to guidance at the beginning of the specification - Patient Care Aggregator Reporting Service API considerations. |
1193 | 1211 | example: https://my.portal.com/Questionnaire/3a146c43-2b21-44e9-95bc-6f4849e504c8 |
1194 | 1212 | owner: |
1195 | 1213 | type: object |
|
0 commit comments