Use case
A consuming system requests available slots from a provider system matching the selected date/time range and for a specific service.
Security
- Utilises a JSON Web Token (JWT) to transmit Consumer system identity and authorisation details.
- Is routed through the SSP (Spine secure Proxy)
- Utilises TLS Mutual Authentication for system level authentication.
Search parameters
Servers MUST support the following search parameters that MAY be passed to the API. In some use cases clients may not be able to support the complete parameter list, so may omit unsupported parameters (so Servers must cater for parameters not being present).
| Name | Type | Description | Paths |
|---|---|---|---|
service |
token |
The appropriate service id of the service for which Slots are being requested. A FHIR SearchParameter has been defined here. |
schedule.actor:healthcareservice |
status |
token |
The free/busy status of the slots Servers must support searching for all statuses. To search for more than one status, use the format status=status1,status2... |
status |
start |
dateTime |
Slot start date/time. A dateTime or Instant in the format yyyy-mm-ddThh:mm:ss+hh:mm. |
start |
NB: to search for time windows within which Slots must start, use “greater than” and “less than” searching - for example GET [base]Slot?start=ge2010-01-01&start=le2011-12-31. Additional query parameters MAY be used. However, if these are not supported by the Server, they SHOULD be ignored.
_include parameters
Provider systems SHOULD support the following include parameters. However, if a resource is not supported, then only supported resources MUST be returned, rather than an error.
Consumer systems should not expect all resources to be returned. If the resource is not supported by the provider, then the resource will simply not be returned and no error will be displayed.
Parameter format
Parameter values for both _include and _revinclude have three parts, separated by a : character:
- The name of the source resource from which the join comes
- The name of the search parameter which must be of type reference
- (Optional) A specific of type of target resource (for when the search parameter refers to multiple possible target types)
| Name | Description | Paths |
|---|---|---|
&_include=Slot:schedule |
Include Schedule Resources referenced within the returned Slot Resources | Slot:schedule |
&_include:iterate=Schedule:actor:Practitioner |
Include Practitioner Resources referenced within the returned Schedule Resources | Schedule:actor:Practitioner |
&_include:iterate=Schedule:actor:PractitionerRole |
Include Practitioner Role Resources referenced within the returned Schedule Resources | Schedule:actor:PractitionerRole |
&_include:iterate=Schedule:actor:HealthcareService |
Include HealthcareService Resources referenced within the returned Schedule Resources | Schedule:actor:HealthcareService |
&_include:iterate=HealthcareService:Organization |
Include Organization Resources referenced within the returned HealthcareService Resources | HealthcareService:Organization |
&_include:iterate=HealthcareService:Location |
Include Location Resources referenced within the returned HealthcareService Resources | HealthcareService:Location |
In the event that an include is formed part of a slot request, but the providing system does not hold that the data then the providing system should return an empty element for that data item. Available slots must still be returned to the consumer and the booking of these slots supported.
_format
The request can be formatted to the following MIME types:
| JSON | _format=xml |
| XML | _format=json |
RESTful Query
The request body is sent using an http GET method.
The following query demonstrates a full request for information:
|
http://[FHIR base URL]/Slot ?schedule.actor:healthcareservice=918999198999 &start=ge2019-05-09T10:00:00+00:00 &start=le2019-05-09T10:30:00+00:00 &status=free &_include=Slot:schedule &_include:iterate=Schedule:actor:Practitioner &_include:iterate=Schedule:actor:PractitionerRole &_include:iterate=Schedule:actor:HealthcareService &_include:iterate=HealthcareService:location &_format=json |
Response
Success
Provider systems:
- MUST return a
200OK HTTP status code on successful retrieval of slot details. - MUST include the
Slotresources which meet the requested criteria. - MAY implement paging as described here to limit the number of resources returned.
- MAY implement an upper limit on returned Slots that excludes Slots which would fall into the requested time window.
The response Bundle MUST only contain resources related to the returned Slot resources. If no free slots are returned then no resources SHOULD be returned within the response Bundle. Related resources SHOULD NOT be duplicated (where for example they are related to multiple Slots).
Failure
Provider systems:
-
If the request fails because either no valid JWT is supplied or the supplied JWT failed validation, the response MUST include a status of
403Forbidden. This MUST be accompanied by an OperationOutcome resource providing additional detail. - If the request fails because the query string parameters were invalid or unsupported, the response MUST include a status of
400Bad Request. - If the request fails because of a server error, the response MUST include a status of
500Internal Server Error.
Failure responses with a 4xx status SHOULD NOT be retried without taking steps to address the underlying cause of the failure.
Failure responses with a 500 status MAY be retried.
Sample response
{
"resourceType": "Bundle",
"id": "a56382a1-dce2-483a-8426-65b727b66809",
"meta": {
"lastUpdated": "2019-05-09T09:26:12.010+00:00"
},
"type": "searchset",
"total": 8,
"link": [
{
"relation": "self",
"url": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/Slot?_format=json&_include=Slot%3Aschedule&_include=Schedule%3Aactor%3APractitioner&_include=Schedule%3Aactor%3APractitionerRole&_include=Schedule%3Aactor%3AHealthcareService&_include=HealthcareService.location&schedule.actor%3Ahealthcareservice=918999198999&start=ge2019-05-09T10%3A00%3A00%2000%3A00&start=le2019-05-09T10%3A30%3A00%2000%3A00&status=free"
}
],
"entry": [
{
"fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/Slot/slot005",
"resource": {
"resourceType": "Slot",
"id": "slot005",
"meta": {
"profile": [
"https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Slot-1"
]
},
"identifier": [
{
"system": "https://tools.ietf.org/html/rfc4122",
"value": "5a889965-3db4-4c29-8003-676c247a763e"
}
],
"schedule": {
"reference": "Schedule/sched1111"
},
"status": "free",
"start": "2019-05-09T10:00:00.000+00:00",
"end": "2019-05-09T10:15:00.000+00:00"
}
},
{
"fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/Slot/slot006",
"resource": {
"resourceType": "Slot",
"id": "slot006",
"meta": {
"profile": [
"https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Slot-1"
]
},
"identifier": [
{
"system": "https://tools.ietf.org/html/rfc4122",
"value": "d939f0e0-d434-4962-a327-7ed52fde2b2e"
}
],
"schedule": {
"reference": "Schedule/sched1111"
},
"status": "free",
"start": "2019-05-09T10:15:00.000+00:00",
"end": "2019-05-09T10:30:00.000+00:00"
}
},
{
"fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/Slot/slot007",
"resource": {
"resourceType": "Slot",
"id": "slot007",
"meta": {
"profile": [
"https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Slot-1"
]
},
"identifier": [
{
"system": "https://tools.ietf.org/html/rfc4122",
"value": "50360c34-c1e0-42dd-b965-8e4dd79ed902"
}
],
"schedule": {
"reference": "Schedule/sched1111"
},
"status": "free",
"start": "2019-05-09T10:30:00.000+00:00",
"end": "2019-05-09T10:45:00.000+00:00"
}
},
{
"fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/Schedule/sched1111",
"resource": {
"resourceType": "Schedule",
"id": "sched1111",
"meta": {
"profile": [
"https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Schedule-1"
]
},
"identifier": [
{
"system": "https://system.supplier.co.uk/MyDiary/Numbering",
"value": "1015432"
}
],
"actor": [
{
"reference": "HealthcareService/918999198999"
},
{
"reference": "Practitioner/ABCD123456"
}
]
}
},
{
"fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/HealthcareService/918999198999",
"resource": {
"resourceType": "HealthcareService",
"id": "918999198999",
"meta": {
"profile": [
"https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-HealthcareService-1"
]
},
"identifier": [
{
"system": "https://system.supplier.co.uk/My/Services",
"value": "357"
}
],
"location": [
{
"reference": "Location/loc2222"
}
],
"name": "Service One"
}
},
{
"fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/Practitioner/ABCD123456",
"resource": {
"resourceType": "Practitioner",
"id": "ABCD123456",
"meta": {
"profile": [
"https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Practitioner-1"
]
},
"identifier": [
{
"system": "https://fhir.nhs.uk/Id/sds-user-id",
"value": "ABCD123456"
},
{
"system": "https://fhir.nhs.uk/Id/sds-role-profile-id",
"value": "R0260"
}
],
"name": [
{
"family": "Webber",
"given": [
"Libbie"
],
"prefix": [
"Dr"
]
}
]
}
},
{
"fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/PractitionerRole/R0260",
"resource": {
"resourceType": "PractitionerRole",
"id": "R0260",
"meta": {
"profile": [
"https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-PractitionerRole-1"
]
},
"code": [
{
"coding": [
{
"system": "https://fhir.hl7.org.uk/STU3/CodeSystem/CareConnect-SDSJobRoleName-1",
"code": "R0260",
"display": "General Medical Practitioner"
}
]
}
]
}
},
{
"fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/Location/loc1111",
"resource": {
"resourceType": "Location",
"id": "loc1111",
"meta": {
"profile": [
"https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Location-1"
]
},
"name": "Location One"
}
}
]
}