Migrating away from the SDS LDAP API

The Spine Directory Service (SDS) LDAP API is deprecated. In due course it will be retired, although we haven't yet decided on a retirement date.

If you have an application that uses the API, you'll need to change your application to use one or more of the replacement APIs.

This page explains the benefits of migrating and how to migrate.

1. The replacement APIs are internet-facing, whereas the SDS LDAP API can only be used over HSCN. This supports our Internet first architecture principle and allows end users to access systems and data when an HSCN connection isn't available and allows NHS organisations to cut costs by removing the need for an HSCN connection.
2. The replacement APIs are RESTful and thus more familiar to developers maintaining your code than LDAP.
3. The replacement APIs use OAuth 2.0 for security, as opposed to TLS-MA. This means you don't need to worry about renewing your TLS-MA certificates when they expire.
4. The replacement APIs offer, or will in future offer, improved capabilities. For example, in the future it will be possible to obtain a healthcare worker's complete set of national RBAC activities - whether they be directly assigned, inferred from their role, or as an 'included' activity - via CIS2 Authentication and the Healthcare Worker API.
5. The SDS LDAP API will move to a reduced Service Level Agreement in due course and will eventually be retired and unavailable for use.

SDS is a datastore with a hierarchical tree-like structure, much like the folders and files in a computer file system.

The structure has a root (O=nhs) and five top level branches:

• The organisations branch (ou=Organisations)
• The people branch (ou=People)
• The IT systems branch (ou=Services)
• the reference data branch (ou=ReferenceData)
• The change log branch (ou=ChangeLog)

Your migration approach depends on which of the branches you are using.

If you're using the organisations branch, migrate to Organisation Data Terminology - FHIR API.

Note that the ODT API does not provide the ability to set up test organisations in Path to Live (PtL) environments. Instead it has a full copy of all real organisations (from production) in each PtL environment. If you currently use test organisations, you'll need to switch to using real organisations instead.

The people branch holds information on Care Identity Service (CIS) users.

If you're using the people branch to get information about the currently signed in CIS user:

1. if you're still using CIS1 Authentication to authenticate the user, migrate to CIS2 Authentication
2. use the CIS2 Authentication user info endpoint to get the user's information

If you're using the people branch to get information about a CIS user who isn't currently signed in, migrate to Healthcare Worker - FHIR API.

We know there are some gaps in this API and we're working on a roadmap to fill those gaps.

If you're using the IT systems branch (ou=Services), your options depend on the context.

Your options are listed below:

Technical guidance

For details of the changes you'll need to make to your software to integrate with the Spine Directory Service FHIR API, see our GP Connect guidance on the Spine Directory Service.

Onboarding

We've developed a lightweight onboarding process for the migration to the SDS FHIR API using our Digital Onboarding Service. To get started with onboarding, contact the GP Connect onboarding team at [email protected].

If your context is as a consumer of NHS Booking API (also sometimes referred to as 'Care Connect'), migrate to Spine Directory Service - FHIR API.

We are unable to advise you to migrate to Booking and Referral - FHIR API because that would require all provider systems to migrate to BaRS, and currently we have no active plans to make this happen.

We're working on developing an onboarding process for the migration to the SDS FHIR API. We'll let you know when it's available.

If you are using the SDS LDAP API to look up details of national services for HL7 V3 messaging, your options are listed below.

If you're using the reference data branch, contact us.

If you're using the change log branch, contact us.

If you have any questions about migration, including use cases that our replacement APIs don't support, you can get help and support via the NHS England Customer Portal (SDS LDAP deprecation enquiry form).