Design
Design specifications and requirements for Spine FHIR APIs including:Spine Directory Services (SDS)
Device and Endpoint endpoints providing Search interactions enabling:- Look up a provider’s endpoint and ASID
- Look up a consumer’s own ASID
Design overview
The SDS API design will follow the guiding design principle that the API seeks to hide legacy complexity where possible.
The SDS API will fully hide the consumer from details of the ldap query used to convey SDS information to and from Spine.
Device Data Mapping
This table specifies the mapping from data requirements, Accredited System record, to FHIR targets within the SDS-Device resource
| Data Item | LDAP Attribute | Cardinality | FHIR Target | Notes |
|---|---|---|---|---|
| Accredited System Identifier | uniqueIdentifier | 1 | Device.identifier:NhsSpineASID | |
| Managing Organisation Code | nhsIdCode | 1 | Device.extension:managingOrganisation (for GP System supplier) | |
| Client Code | nhsAsClient | 0..* | Device.owner (for GP System i.e. GP Practice) | List of Organisation or Site codes, or Organisational Work Groups which use this Accredited System. Though the cardinality is set to 0..*, EPR application ensures there is 1 value in this attribute. |
| Party Key | nhsMhsPartyKey | 1 | Device.identifier:NhsMhsPartyKey | |
| Service-Interactions | nhsAsSvcIA | 1..* | Device.identifier:NhsEndpointServiceId | |
| ACF Characteristics | nhsAsACF | 0..* | not mapped - not returned | |
| Description | description | 0..1 | not mapped - not returned | |
| Category Bag | nhsAsCategoryBag | 0..* | not mapped - not returned | |
| Product | nhsProductKey | 1 | not mapped - not returned | |
| Requestor’s Identity | nhsRequestorURP | 1 | not mapped - not returned | |
| Date Requested | nhsDateRequested | 1 | not mapped - not returned | |
| Approver’s Identity | nhsApproverURP | 1 | not mapped - not returned | |
| Date Approved | nhsDateApproved | 1 | not mapped - not returned |
not mapped - not returned - these data items in the AccreditedSystem record are not returned by the Device endpoint and so are not mapped to a FHIR Target
Device Search Interactions
The SCR API SHALL support a search interaction to return Device resources using search parameters for:- [Mandatory] Organisation code - ODS code of the target organisation (i.e. GP practice operating the software instance)
- [Mandatory] MHS Interaction ID - type of Interaction supported by software instance
- [Optional ] Manufacturer's organisation code - ODS code of the manufacturer's organisation (i.e. GP System supplier)
- [Optional ] Party Key - identifier representing the target organisation and service interaction
Search Parameter
| Data Item | Query Parameter | Query Target | Example |
|---|---|---|---|
| Organisation code | organization | Device.owner | organization=[GPSystemODSCode] |
| MHS Interaction ID | identifier | Device.identifier:NhsEndpointServiceId | identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|[interactionId] |
| Manufacturer organisation code | managing-organisation | Device.extension:Extension-SDS-ManagingOrganisation | managing-organisation=[supplierODSCode] |
| Party Key | identifier | Device.identifier:NhsMhsPartyKey | identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKey|[partyKey] |
Request pattern
GET [baseURL]/Device?
organization=[ODSNamingSystem]|[GPSystemODSCode]&
identifier=[EndpointServiceIdNamingSystem]|[interactionId]&
managing-organisation=[ODSNamingSystem]|[supplierODSCode]&
identifier=[PartyKeyNamingSystem]|[partyKey]
Example request
GET [baseURL]/Device?
organization=https://fhir.nhs.uk/Id/ods-organization-code|R8008&
identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05&
managing-organisation=https://fhir.nhs.uk/Id/ods-organization-code|T10101&
identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKey|R8008-0000806
Example response payload
<url value="[baseURL]/Device?organization=https://fhir.nhs.uk/Id/ods-organization-code|R8008&identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05&managing-organisation=https://fhir.nhs.uk/Id/ods-organization-code|T10101&identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKey|R8008-0000806" />
</link>
<Device>
</identifier>
</valueReference>
</extension>
</identifier>
</identifier>
</identifier>
</identifier>
</owner>
</Device>
</resource>
</search>
</entry>
</Bundle>
{
{
"url": "[baseURL]/Device?organization=https://fhir.nhs.uk/Id/ods-organization-code|R8008&identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05&managing-organisation=https://fhir.nhs.uk/Id/ods-organization-code|T10101&identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKey|R8008-0000806"
}
],
{
{
},
}
}
],
{
},
{
},
{
}
],
},
}
},
}
}
]
}
Endpoint Data Mapping
This table specifies the mapping from data requirements, Message Handling System (MHS) record, to FHIR targets within the SDS-Endpoint resource
| Data Item | LDAP Attribute | Cardinality | FHIR Target |
|---|---|---|---|
| Organisation Code | nhsIdCode | 1 | Endpoint.managingOrganization |
| Service-Interaction | nhsMhsSvcIA | 1 | Endpoint.identifier:NhsEndpointServiceId |
| FQDN of MHS | nhsMHSFQDN | 1 | Endpoint.identifier:NhsMhsFQDN |
| End Point | nhsMhsEndPoint | 1 | Endpoint.address |
| Party Key | nhsMhsPartyKey | 1 | Endpoint.identifier:NhsMhsPartyKey |
| CPA Identifier | nhsMhsCPAId | 1 | Endpoint.identifier:NhsMhsCPAId |
| MHS Identifier | uniqueIdentifier | 1 | Endpoint.identifier:NhsSpineASID |
| Sync Reply Mode | nhsMhsSyncReplyMode | 0..1 | Endpoint.extension:ExtensionSDSReliabilityConfiguration.extension:nhsMHSSyncReplyMode |
| Retry Interval | nhsMhsRetryInterval | 0..1 | Endpoint.extension:ExtensionSDSReliabilityConfiguration.extension:nhsMHSRetryInterval |
| Retries | nhsMhsRetries | 0..1 | Endpoint.extension:ExtensionSDSReliabilityConfiguration.extension:nhsMHSRetries |
| Persist duration | nhsMhsPersistduration | 0..1 | Endpoint.extension:ExtensionSDSReliabilityConfiguration.extension:nhsMHSPersistDuration |
| Duplicate Elimination | nhsMhsDuplicateElimination | 0..1 | Endpoint.extension:ExtensionSDSReliabilityConfiguration.extension:nhsMHSDuplicateElimination |
| Ack Requested | nhsMhsAckRequested | 0..1 | Endpoint.extension:ExtensionSDSReliabilityConfiguration.extension:nhsMHSAckRequested |
| Actor | nhsMhsActor | 0..1 | Endpoint.extension:ExtensionSDSReliabilityConfiguration.extension:nhsMHSActor |
Endpoint Search Interactions
The SCR API SHALL support a search interaction to return Endpoint resources using search parameters for:- [Mandatory] Organisation code - ODS code of the target organisation (i.e. GP practice exposing the endpoint)
- [Mandatory] MHS Interaction ID - type of Interaction supported by Endpoint
Search Parameter
| Data Item | Query Parameter | Query Target | Example |
|---|---|---|---|
| Organisation code | organization | managingOrganization | organization=[targetODSCode] |
| MHS Interaction ID | identifier | Endpoint.identifier:NhsEndpointServiceId | identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|[interactionId] |
Request pattern
GET [baseURL]/Endpoint?
organization=[ODSNamingSystem]|[targetODSCode]&
identifier=[EndpointServiceIdNamingSystem]|[interactionId]
Example request
GET [baseURL]/Endpoint?
organization=https://fhir.nhs.uk/Id/ods-organization-code|R8008&
identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05
Example response payload
<url value="[baseURL]/Endpoint?organization=https://fhir.nhs.uk/Id/ods-organization-code|R8008&identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05" />
</link>
<Endpoint>
</extension>
</extension>
</extension>
</extension>
</extension>
</extension>
</extension>
</extension>
</identifier>
</identifier>
</identifier>
</identifier>
</identifier>
</identifier>
</connectionType>
</identifier>
</managingOrganization>
</coding>
</payloadType>
</Endpoint>
</resource>
</search>
</entry>
</Bundle>
{
{
"url": "[baseURL]/Endpoint?organization=https://fhir.nhs.uk/Id/ods-organization-code|R8008&identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05"
}
],
{
{
{
},
{
},
{
},
{
},
{
},
{
},
{
}
]
}
],
{
},
{
},
{
},
{
},
{
},
{
}
],
},
},
{
{
}
]
}
],
},
}
}
]
}
Modules
Important: This page is under development by NHS Digital