Skip to content

Commit

Permalink
NPA-1711: add background API documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
James Taylor committed Jan 19, 2024
1 parent f55743e commit c86b499
Showing 1 changed file with 117 additions and 27 deletions.
144 changes: 117 additions & 27 deletions specification/validated-relationships-service-api.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,61 +6,151 @@ info:
version: 'Computed and injected at build time by `scripts/set_version.py`'
description: |
## Overview
This is an Open API specification for the Validated Relationship Service.
To be completed.
Use this API to access the Validated Relationships Service - the national electronic database of relationships that have been verified for the purpose of enabling individuals to access healthcare services on behalf of (proxy) those they care for.
You can:
For help completing the content of your API spec, see [our guidance](https://nhsd-confluence.digital.nhs.uk/display/APM/Documenting+your+API).
You should also base your content on our exemplar API - [PDS FHIR](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir).
- search for verified relationships for a given proxy
## Who can use this API
To be completed.
This API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go too far with your development. You must demonstrate you have a valid use case as part of digital onboarding.
You must do this before you can go live (see 'Onboarding' below).
## Related APIs
To be completed.
The following APIs are related to this API:
- [Personal Demographics Service - FHIR API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir) - we use the data held in PDS as a source of data to verify relationships.
## API status and roadmap
To be completed.
### Patient access
This access mode is [in production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), meaning:
- we might make breaking changes, but only if we cannot avoid it, and we will give advance notice
If you would like to be involved in our beta programme, [contact us](https://digital.nhs.uk/developer/help-and-support).
### Roadmap
To see our roadmap, or to suggest, comment or vote on features for this API, see our [interactive product backlog - LINK NEEDED]().
If you have any other queries, please [contact us](https://digital.nhs.uk/developer/help-and-support).
## Service level
To be completed.
This API is a bronze service, meaning it is operational 24 hours a day, 365 days a year and supported during business hours (8am to 6pm, Monday to Friday excluding bank holidays).
For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).
## Technology
To be completed.
This API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).
It conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir) global standard for health care data exchange, specifically to [FHIR R4 (v4.0.1)](https://hl7.org/fhir/r4/), except that it does not support the [capabilities](http://hl7.org/fhir/R4/http.html#capabilities) interaction.
It includes some country-specific FHIR extensions, which are built against [FHIR UK Core](https://digital.nhs.uk/services/fhir-uk-core), specifically [UK.core.r4 1.0.0](https://simplifier.net/packages/uk.core.r4/1.0.0).
You do not need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules.
In particular:
- resource names are capitalised and singular, for example `/Patient` not `/patients`
- array names are singular, for example `line` not `lines` for address lines
- data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an `extension` object
There are [libraries and SDKs available](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) to help with FHIR API integration.
### Open source
To be completed.
You might find the following [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) resources useful:
| Resource | Description | Links |
|---------------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------|
| Validated Relationships FHIR API | Source code for the API proxy, sandbox and specification. | [GitHub repo](https://github.com/NHSDigital/validated-relationships-service-api) |
| FHIR libraries and SDKs | Various open source libraries for integrating with FHIR APIs. | [FHIR libraries and SDKs](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) |
| nhs-number | Python package containing utilities for NHS numbers including validity checks, normalisation and generation. | [GitHub repo](https://github.com/uk-fci/nhs-number) \| [Python Package index](https://pypi.org/project/nhs-number/) \| [Docs](https://nhs-number.uk-fci.tech/) |
We currently don't have any open source client libraries or sample code for this API. If you think this would be useful, you can [upvote the suggestion on our Interactive Product Backlog](https://nhs-digital-api-management.featureupvote.com/suggestions/107439/client-libraries-and-reference-implementations).
The source code for the PDS FHIR back end (the Core Spine source code) is not currently in the open. If you think this would be useful, you can [upvote the suggestion on our Interactive Product Backlog](https://nhs-digital-api-management.featureupvote.com/suggestions/466692/open-source-core-spine-including-pds-eps-scr-and-more).
## Network access
To be completed.
This API is available on the internet.
For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).
## Security and authorisation
To be completed.
This API has one access mode:
- patient access
### Patient access
Use this access mode if you wish to perform the following on behald of a user:
* get the patients a person can act on behalf of (proxy for)
This access mode is [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis), meaning an end user must be present, authenticated and authorised.
The end user must be:
* a patient who receives health and social care or makes use of NHS services
* strongly authenticated, using [NHS login](https://digital.nhs.uk/services/nhs-login)
To use this access mode, use one of the following security patterns:
| Security pattern | Technical details | Advantages | Disadvantages |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------------------------------------------------| ------------------------------------------------------------|---------------------------------------------------------|
|[NHS login - combined authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-combined-authentication-and-authorisation) |OAuth 2.0 authorisation code with API key and secret |No need to integrate and onboard separately with NHS login. |No access to user information. |
|[NHS login - separate authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation) |OAuth 2.0 token exchange with signed JWT |Gives access to user information. |Need to integrate and onboard separately with NHS login. |
## Environments and testing
To be completed.
| Environment | Base URL |
| ----------------- | ---------------------------------------------------------------------- |
| Sandbox | `https://sandbox.api.service.nhs.uk/validated-relationships/FHIR/R4/` |
| Integration test | `https://int.api.service.nhs.uk/validated-relationships/FHIR/R4/` |
| Production | `https://api.service.nhs.uk/validated-relationships/FHIR/R4/` |
### Sandbox testing
TO BE COMPLETED
### Integration testing
TO BE COMPLETED
### Production smoke testing
TO BE COMPLETED
## Onboarding
To be completed.
## Errors
To be completed.
We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:
* 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
* 400 to 499 if it failed because of a client error by your application
* 500 to 599 if it failed because of an error on our server
Errors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.
contact:
name: 'Validated Relationships Service API Support'
url: 'https://digital.nhs.uk/developer/help-and-support'
email: [email protected]
servers:
- url: 'https://sandbox.api.service.nhs.uk/validated-relationships'
- url: 'https://sandbox.api.service.nhs.uk/validated-relationships/FHIR/R4'
description: Sandbox environment.
- url: 'https://int.api.service.nhs.uk/validated-relationships'
- url: 'https://int.api.service.nhs.uk/validated-relationships/FHIR/R4'
description: Integration test environment.
- url: 'https://api.service.nhs.uk/validated-relationships'
- url: 'https://api.service.nhs.uk/validated-relationships/FHIR/R4'
description: Production environment.
paths:
/RelatedPerson:
get:
summary: Get relationships.
parameters:
- $ref: "#/components/parameters/BearerAuthorisation"
- $ref: "#/components/parameters/proxyID"
- $ref: "#/components/parameters/patientID"
- $ref: "#/components/parameters/RelatedPersonIdentifier"
- $ref: "#/components/parameters/PatientIdentifier"
- $ref: "#/components/parameters/RequestID"
- $ref: "#/components/parameters/CorrelationID"
responses:
"200":
description: Successful retrieval.
content:
application/json:
application/fhir+json:
schema:
$ref: "#/components/schemas/Relationship"
"4XX":
Expand All @@ -78,7 +168,7 @@ paths:
| 408 | `TIMEOUT` | Request timed out. |
| 429 | `THROTTLED` | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
content:
application/json:
application/fhir+json:
schema:
$ref: '#/components/schemas/OperationOutcome'
"500":
Expand All @@ -89,7 +179,7 @@ paths:
| ----------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| 500 | `SERVER_ERROR` | An internal error has occurred when processing the request. |
content:
application/json:
application/fhir+json:
schema:
$ref: '#/components/schemas/OperationOutcome'

Expand Down Expand Up @@ -399,11 +489,11 @@ components:
description: FHIRPath of element(s) related to the error.
example: RelatedPerson.identifier
parameters:
proxyID:
RelatedPersonIdentifier:
in: query
name: identifier
description: |
The proxy's NHS number.
The RelatedPerson's NHS number.
required: false
schema:
type: string
Expand All @@ -415,11 +505,11 @@ components:
value: "https://fhir.nhs.uk/Id/nhs-number/9000000009"
summary: "System and NHS number specified"

patientID:
PatientIdentifier:
in: query
name: patient:identifier
description: |
The patient's NHS number.
The Patient's NHS number.
required: false
schema:
type: string
Expand Down

0 comments on commit c86b499

Please sign in to comment.