Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

Read an appointment

Use case for reading an appointment resource

API use case

This specification describes a single use case enabling the consumer to obtain the details of a specific future appointment from a targeted provider system, irrespective of the booking organisation.

Security

  • GP Connect utilises TLS Mutual Authentication for system level authorization
  • GP Connect utilises a JSON Web Tokens (JWT) to transmit clinical audit and provenance details

Consumer

The consumer system:

API usage

The consumer system SHALL only use the read appointment capability to retrieve future appointments, where the appointment start dateTime is after the current date and time. If the appointment start date is in the past the provider SHALL return an error.

Request operation

FHIR® relative request

GET /Appointment/[id]

FHIR absolute request

GET https://[proxy_server]/https://[provider_server]/[fhir_base]/Appointment/[id]

Request headers

Consumers SHALL include the following additional HTTP request headers:

Header Value
Ssp-TraceID Consumer’s TraceID (i.e. GUID/UUID)
Ssp-From Consumer’s ASID
Ssp-To Provider’s ASID
Ssp-InteractionID urn:nhs:names:services:gpconnect:fhir:rest:read:appointment-1

Payload request body

N/A

Error handling

Provider systems:

  • SHALL return an GPConnect-OperationOutcome-1 resource that provides additional detail when one or more data fields are corrupt or a specific business rule/constraint is breached.
  • SHALL return an error if the appointment being read is in the past (the appointment start dateTime is before the current date and time).

Examples of other scenarios which may result in error being returned:

  • Where a logical identifier of the resource is not valid/can’t be found on the server, a 404 HTTP Status code would be returned with the relevant OperationOutcome resource.
  • Where insufficient data about an appointment is present in the provider system to populate an appointment resource which validates to the GPConnect-Appointment-1 profile, a 500 HTTP Status code should be returned, together with the appropriate OperationOutcome resource providing diagnostic detail.

Refer to Development - FHIR API Guidance - Error Handling for details of error codes.

Request response

Response headers

Provider systems are not expected to add any specific headers beyond that described in the HTTP and FHIR® standards.

Payload response body

Provider systems:

  • SHALL return a 200 OK HTTP status code on successful execution of the operation.
  • SHALL return Appointment resources that conform to the GPConnect-Appointment-1 resource profile.
  • SHALL include the URI of the GPConnect-Appointment-1 profile StructureDefinition in the Appointment.meta.profile element of the returned appointment resource.
  • SHALL include the versionId of the current version of the appointment resource.
  • SHALL include all relevant business identifier details (if any) for the appointment resource.

  • SHALL meet General FHIR resource population requirements populating all fields where data is available, excluding those listed below

  • SHALL NOT populate the following fields:
    • reason
    • specialty
{
  "resourceType": "Appointment",
  "id": "148",
  "meta": {
    "versionId": "1503310820000",
    "profile": [
      "https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Appointment-1"
    ]
  },
  "contained": [
    {
      "resourceType": "Organization",
      "id": "1",
      "meta": {
        "profile": [
          "https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1"
        ]
      },
      "identifier": [
        {
          "system": "https://fhir.nhs.uk/Id/ods-organization-code",
          "value": "A00001"
        }
      ],
      "name": "Test Organization Name",
      "telecom": [
        {
          "system": "phone",
          "value": "0300 303 5678"
        }
      ]
    }
  ],
  "extension": [
    {
      "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-BookingOrganisation-1",
      "valueReference": {
        "reference": "#1"
      }
    },
    {
      "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-PractitionerRole-1",
      "valueCodeableConcept": {
        "coding": [
          {
            "system": "https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-SDSJobRoleName-1",
            "code": "R0260",
            "display": "General Medical Practitioner"
          }
        ]
      }
    },
    {
      "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-DeliveryChannel-2",
      "valueCode": "In-person"
    }
  ],
  "status": "booked",
  "description": "GP Connect Appointment description 148",
  "start": "2017-08-21T10:20:00.000+00:00",
  "end": "2017-08-21T10:50:00.000+00:00",
  "slot": [
    {
      "reference": "Slot/544"
    },
    {
      "reference": "Slot/545"
    },
    {
      "reference": "Slot/546"
    }
  ],
  "created": "2017-10-09T13:48:41+01:00",
  "comment": "Test Appointment Comment 148",
  "participant": [
    {
      "actor": {
        "reference": "Patient/2"
      },
      "status": "accepted"
    },
    {
      "actor": {
        "reference": "Location/1"
      },
      "status": "accepted"
    },
    {
      "actor": {
        "reference": "Practitioner/2"
      },
      "status": "accepted"
    }
  ]
}

Examples

C#

var client = new FhirClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1/");
client.PreferredFormat = ResourceFormat.Json;
var resource = client.Read<Appointment>("Appointment/148");
FhirSerializer.SerializeResourceToJson(resource).Dump();

Java

FhirContext ctx = FhirContext.forStu3();
IGenericClient client = ctx.newRestfulGenericClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1");
Appointment appointment = client.read().resource(Appointment.class).withId("148").execute();
System.out.println(fhirContext.newJsonParser().setPrettyPrint(true).encodeResourceToString(appointment));
Tags: appointments

All content is available under the Open Government Licence v3.0, except where otherwise stated