Merge pull request #70 from NHSDigital/apm-000-respond-to-spec-content-review

Respond to spec content review

Author: deskelleher

specification/patient-care-aggregator-reporting.yaml

@@ -7,20 +7,20 @@ info:
   description: |
   
     ## Overview
-    Use this API to send events which happen within your service boundary to the Wayfinder Reporting Service.
+    Send events which happen within your service boundary to the Wayfinder Reporting Service.
     
-    The Wayfinder Programme requires that key events that take place in all Wayfinder-integrated services be submitted to a central Wayfinder Reporting Service in order for the programme to produce Management Intelligence (MI) in a tool called Wayfinder Insights.
+    The Wayfinder programme requires that key events that take place in all Wayfinder-integrated services be submitted to a central Wayfinder Reporting Service in order for the programme to produce Management Intelligence (MI) in a tool called Wayfinder Insights.
 
     Examples of events from Wayfinder-integrated systems are:
 
     | Service Boundary                                                                   | Example                                                                              |
     |------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
-    |[NHS App](https://www.nhs.uk/nhs-app/)                                              | A session has been started by a user logging into the NHS App                        |
-    |[e-Referrals Service](https://digital.nhs.uk/services/e-referral-service)           | A referral has been viewed by a Wayfinder user in the e-Referrals Service            |
-    |Patient Engagement Portals (PEPs)                                                   | A Wayfinder user has cancelled an appointment in a PEP's user interface.             |
-    |[Patient Care Aggregator](https://digital.nhs.uk/services/patient-care-aggregator)  | A PEP has informed the Patient Care Aggregator that they have questionnaire data for a particular NHS Number|
-    |Patient Engagement Portals (PEPs)                                                   | A PEP has sent an SMS message to a Wayfinder user                                    |
-    |Patient Engagement Portals (PEPs)                                                   | A secondary care trust has informed a PEP that an appointment has been booked        |
+    |[NHS App](https://www.nhs.uk/nhs-app/)                                              | a session has been started by a user logging into the NHS App                        |
+    |[e-Referrals Service](https://digital.nhs.uk/services/e-referral-service)           | a referral has been viewed by a Wayfinder user in the e-Referrals Service            |
+    |Patient Engagement Portals (PEPs)                                                   | a Wayfinder user has cancelled an appointment in a PEP's user interface.             |
+    |[Patient Care Aggregator](https://digital.nhs.uk/services/patient-care-aggregator)  | a PEP has informed the Patient Care Aggregator that they have questionnaire data for a particular NHS Number|
+    |Patient Engagement Portals (PEPs)                                                   | a PEP has sent an SMS message to a Wayfinder user                                    |
+    |Patient Engagement Portals (PEPs)                                                   | a secondary care trust has informed a PEP that an appointment has been booked        |
     
     |                                                                                    |                                                                                      |
     |------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
@@ -35,18 +35,22 @@ info:
 
     All events are related to an parent entity. For example, appointments (APPT) have events indicating that an appointment has been viewed by the user (APPT-VIEW). Questionnaires (QUEST) have events that indicate that a questionnaire has been completed by a user (QUEST-COMPLETE). You must send events for the creation or update of these parent entities if you send events related to those parent entities.
 
-    ## Authorisation
-    This API is [application-restricted with signed JWT authentication]([https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)), meaning we authenticate and authorise the calling application but we do not authenticate or authorise the end user.
-
-    In this pattern, you authenticate your application by sending a signed JSON Web Token (JWT) to our OAuth 2.0 authorisation server. You provide us with your public key and sign the JWT with your private key. In return, we give you an access token, which you then include with each API request.
-
     ## Who can use this API
     This API is for Wayfinder-internal use only.
     
     If you are interested in using this API in another context, [contact us](https://digital.nhs.uk/developer/help-and-support).
+
+    In this pattern, you authenticate your application by sending a signed JSON Web Token (JWT) to our OAuth 2.0 authorisation server. You provide us with your public key and sign the JWT with your private key. In return, we give you an access token, which you then include with each API request.
     
+    ## Related APIs
+    - [Patient Care Aggregator - FHIR API](https://digital.nhs.uk/developer/api-catalogue/patient-care-aggregator-fhir). Get an aggregated list of referrals and bookings for a patient from secondary care providers.
+
+    - [Patient Care Aggregator Get Appointments API standard](https://digital.nhs.uk/developer/api-catalogue/patient-care-aggregator-get-appointments). As a secondary care provider, provide a list of bookings for a patient to the Patient Care Aggregator.
+
+    - [Patient Care Aggregator Record Service API](https://digital.nhs.uk/developer/api-catalogue/patient-care-aggregator-record-service/patient-care-aggregator-record-service-api). As a secondary care provider, let the Patient Care Aggregator know which patients you have bookings for.
+
     ## API status
-    This API is [in production, beta but internal](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), meaning the API is not currently available for integration by external third parties. If you want to use it, [contact us](https://digital.nhs.uk/developer/help-and-support) and we'll look at making it available.
+    This API is [in production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses) but internal, meaning the API is not currently available for integration by external third parties. If you want to use it, [contact us](https://digital.nhs.uk/developer/help-and-support) and we'll look at making it available.
         
     If you would still like to be involved in our beta programme or use this API, [contact us](https://digital.nhs.uk/developer/help-and-support).
 
@@ -77,7 +81,10 @@ info:
     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).
 
     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 is [application-restricted with signed JWT authentication]([https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)), meaning we authenticate and authorise the calling application but we do not authenticate or authorise the end user.        
+
     ## Environments and testing
     | Environment       | Base URL                                                                        |
     | ----------------- | ------------------------------------------------------------------------------- |
@@ -112,17 +119,34 @@ info:
     |------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
 
     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 resources useful:
+
+    | Resource | Description  | Links |
+    |---------------------------------------|-----------------------------------------------------------|--------------------------------------------------------------------------------|
+    | Patient Care Aggregator Reporting API | Source code for the API proxy, sandbox and specification.  | [GitHub repo](https://github.com/NHSDigital/patient-care-aggregator-reporting) |                                    
+    | 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) |
+
+    We currently don't have any open source client libraries or sample code for this API. If you think this would be useful, you can upvote the suggestion on our Interactive Product Backlog.
+
 servers:
   - url: "https://int.api.service.nhs.uk/patient-care-aggregator-reporting/"
     description: "Integration (AOS)"
   - url: "https://api.service.nhs.uk/patient-care-aggregator-reporting"
+
     description: "Production"
 paths:
   /:
     post:
       summary: "Send Event(s) to the Wayfinder Reporting Service"
-      description: "Accepts a JSON array of objects, each representing an event within your Wayfinder services's boundary."
+      description: | 
+        Accepts a list of events related to actions in the Wayfinder architecture. For example:
+        - when a user has logged into the NHS App
+        - when a user cancels an appointment in a PEP system
+        - when the Aggregator receives a record from a PEP.
+        
+        Please ensure to check the scopes detailed in each event to confirm if the event is in your given scope.
       parameters:
         - in: "header"
           name: "X-Correlation-ID"