GP Connect Meta API

openapi: 3.2.0
info:
  title: '[DRAFT]gp-connect-update-record-fhir Meta API'
  version: draft
  description: "# Overview\nUse this API to send structured data to a patient's GP record. You can send data related to the patient for the following areas:\n- medications\n- encounters\n- observations\n\nFor the first iteration of this API, only a pharmacy use-case has been approved. Common use cases for this capability include:\n\n- a pharmacy informing the GP that a patient has been prescribed antibiotics\n- a pharmacy informing a GP that a patient has had their blood pressure checked\n\n# Who can use this API\nThis API can be used by developers of clinical systems who have the need to update a patient's GP record.\n\nMake sure you have a valid use case before you go too far with your development.\nYou must do this before you can go live (see 'Onboarding' below).\n## Prerequisites\n### Technical \n\nYou must:\n\n- have access to the [Health and Social Care Network (HCSN)](https://digital.nhs.uk/services/health-and-social-care-network)\n - be [Personal Demographics Service (PDS)](https://digital.nhs.uk/services/demographics) compliant or capable of performing a PDS search to obtain the patient's registered GP\n - be [Spine Directory Service (SDS)](https://developer.nhs.uk/apis/gpconnect-0-5-0/integration_spine_directory_service.html) compliant to be able to obtain the endpoint of the registered GP\n### Information governance\n You must:\n - be compliant with the GP Connect Direct Care API Information Governance Model\n - be using the GP Connect APIs for direct care purposes for NHS patients in England\n \n ### Clinical safety\nYou must:\n- have a clinical safety officer (CSO) who is responsible for DCB0129 and, if necessary, DCB0160. For more details on clinical risk management, see Clinical risk management standards.\nIf you are confident that you can meet the prerequisites, contact us to express your interest. See 'Onboarding' below.\n# Related APIs\n  The following APIs are related to this API:\n  - [GP Connect Access Record: Structured - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-access-record-structured-fhir) - retrieve structured information from a patient's GP practice record.\n  - [GP Connect Send Document - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-send-document-fhir) - send a PDF consultation summary to a registered GP practice.\n\n# API status and roadmap\nThis API is in [development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).\n# Service level\nThis API is a silver service, meaning it is operational 24 hours a day, 365 days a year but only supported during business hours (8am to 6pm), Monday to Friday excluding bank holidays.\nFor more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\n# Technology\nThis is a FHIR API which conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir) global standard for health care data exchange. Specifically, it is aligned with the GP Connect Data Model which is a FHIR STU3 representation.  \n\nThe API requires the provider to send a HTTP request containing a FHIR payload to the provider endpoint. \n\nThe payload will contain clinical information about the patient - for example, medications,  encounters and observations.\nFor more details, see [Update Record implementation guide](https://simplifier.net/guide/gp-connect-update-record?version=current) to assist with your development.\n# Network access\nYou can access this API via the [Health and Social Care Network](https://digital.nhs.uk/services/health-and-social-care-network).\n\nThe API is not currently available over the internet, but we plan to enable public internet access in the future.\nFor more details, see [Network access for APIs.](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis)\n# Security and authorisation\n## Security\nAccess to the GP Connect APIs is controlled and protected by the Spine Secure Proxy (SSP), a forward HTTP proxy.\n\nIt provides a single security point for both authentication and authorisation for consuming systems. Additional responsibilities include auditing of requests, checking data sharing agreements and transaction logging.\n\nAll HTTP communications are secured using [TLS-MA](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis). This includes both legs of the request, from consumer system to the proxy and then from the proxy to provider system.\n\n## Authorisation\nAuthorisation takes place in two locations: \n\n- the consumer system\n- the SSP\n\nThe consumer system must have local [RBAC](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/national-rbac-for-developers) in place and restrict GP Connect APIs to authorised users. With each request, a JSON Web Token (JWT) must be included with the following information:\n-  details of users, including role\n-  where smartcards are used in the consumer system, including SDS user and role IDs\n- details of the consumer system\n- details of the consumer’s organisation, including ODS code\n\nThe information in the JWT is retained for audit purposes.\n\nThe SSP checks data-sharing agreements to ensure that the consumer system is authorised to communicate with the provider system.\n\n# Environments and testing\n\nTBD\n\n# Onboarding\n\nThis API is currently not available for onboarding.\n\n## Expressing an interest\n\nIf you meet the prerequisites and have a product that can integrate with GP Connect, you should express an interest with us by submitting a use case. \n\nThe main purpose of the use case is to help us understand how you plan to use GP Connect APIs and the business issue you are looking to address. \n\nYou should email your use case to us at gpconnect@nhs.net. Your use case should include the following information as a minimum:\n- the business problem you are intending to solve using GP Connect\n- how GP Connect will be used in practice to benefit patients and staff\n- which of the GP Connect products you will use to benefit patients and staff\n- any end user organisations you are currently working with\n- who your clinical safety officer is and, where available, your clinical risk management process documentation\n\n## Consumer assurance process\n\nOnce we approve your use case, we support you through the assurance process to go live. We will discuss the assurance process and artefacts with you to hel you understand our requirements\n\nStart your development work within 6 months of use case approval. If you miss this date, a review or new submission of the use case will be required. Changes or additional development will also require a review or new use case submission. \n\n# Errors\n\nWe use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:\n\n- 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action\n\n- 400 to 499 if it failed because of a client error by your application\n\n- 500 to 599 if it failed because of an error on our server\n\nErrors are returned as a [GP Connect-OperationOutcome-1](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--GPConnect-OperationOutcome-1?version=current) resource in the event of an error. This provides additional detail to the user on the cause of the error.\n"
tags:
- name: Meta
paths:
  /meta:
    get:
      operationId: get-capabilitystatement
      summary: Get update record FHIR capability statement
      description: ''
      parameters:
      - in: header
        name: SSP-Trace-ID
        description: 'The provider''s Trace ID (normally a GUID  or UUID)

          '
        required: true
        schema:
          type: string
      - in: header
        name: SSP-From
        description: 'The provider''s ASID

          '
        required: true
        schema:
          type: string
      - in: header
        name: SSP-To
        description: 'The consumer''s ASID

          '
        required: true
        schema:
          type: string
      - in: header
        name: SSP-InteractionID
        description: 'urn:nhs:names:services:gpconnect:structured:fhir:rest:read:metadata-1

          '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/fhir+json:
              schema:
                type: object
                description: 'FILL THIS OUT

                  '
              examples:
                example:
                  description: Succesful capability statement retrieval
                  value:
                    resourceType: CapabilityStatement
                    version: 1.0.0
                    name: GP Connect API - Update Record
                    status: active
                    date: '2020-02-10'
                    publisher: '[Provider Software Vendor Name]'
                    contact:
                    - name: '[Provider Software Vendor Contact Name]'
                    description: This server implements the GP Connect API - Update Record version 1.0.0
                    copyright: Copyright NHS Digital 2016-21
                    kind: capability
                    software:
                      name: '[Provider Software Name]'
                      version: '[Provider Software Version]'
                      releaseDate: '[Provider Software Release Date]'
                    fhirVersion: 3.0.1
                    acceptUnknown: both
                    format:
                    - application/fhir+json
                    - application/fhir+xml
                    profile:
                    - reference: https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Patient-1/_history/1.8
                    - reference: https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1/_history/1.4
                    - reference: https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Practitioner-1/_history/1.2
                    - reference: https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-MedicationStatement-1/_history/1.7
                    - reference: https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-StructuredRecord-Bundle-1/_history/1.3
                    - reference: https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-OperationOutcome-1/_history/1.2
                    - reference: https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Encounter-1/_history/1.5
                    - reference: https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Observation-1/_history/1.7
                    rest:
                    - mode: server
                      security:
                        cors: true
        4XX:
          description: "An error occured as follows:\n\n\n| HTTP Status | Error code   | Description\n|-------------|--------------------|------------\n| 403         | ACCESS DENIED   | GP Connect is not enabled at the practice\n  403         | ACCESS DENIED      | The Update Record Structured capability is not enabled at the practice\n"
          content:
            application/fhir+json:
              schema:
                type: object
                description: Link
              examples:
                example:
                  value:
                    resourceType: OperationOutcome
                    meta:
                      profile:
                      - https://fhir.hl7.org.uk/StructureDefinition/GPConnect-OperationOutcome-1
                    issue:
                    - severity: error
                      code: value
                      details:
                        coding:
                        - system: https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1
                          code: ACCESS DENIED
                          display: GP Connect is not enabled at the practice
      tags:
      - Meta