You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
version: 'Computed and injected at build time by `scripts/set_version.py`'
7
7
description: |
8
8
## Overview
9
-
This is an Open API specification for the Validated Relationship Service.
10
-
11
-
To be completed.
9
+
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.
10
+
11
+
You can:
12
12
13
-
For help completing the content of your API spec, see [our guidance](https://nhsd-confluence.digital.nhs.uk/display/APM/Documenting+your+API).
14
-
You should also base your content on our exemplar API - [PDS FHIR](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir).
13
+
- search for verified relationships for a given proxy
14
+
15
15
## Who can use this API
16
-
To be completed.
16
+
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.
17
+
18
+
You must do this before you can go live (see 'Onboarding' below).
19
+
17
20
## Related APIs
18
-
To be completed.
21
+
The following APIs are related to this API:
22
+
23
+
- [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.
24
+
19
25
## API status and roadmap
20
-
To be completed.
26
+
27
+
### Patient access
28
+
This access mode is [in production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), meaning:
29
+
- we might make breaking changes, but only if we cannot avoid it, and we will give advance notice
30
+
31
+
If you would like to be involved in our beta programme, [contact us](https://digital.nhs.uk/developer/help-and-support).
32
+
33
+
### Roadmap
34
+
To see our roadmap, or to suggest, comment or vote on features for this API, see our [interactive product backlog - LINK NEEDED]().
35
+
36
+
If you have any other queries, please [contact us](https://digital.nhs.uk/developer/help-and-support).
37
+
21
38
## Service level
22
-
To be completed.
39
+
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).
40
+
41
+
For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).
42
+
23
43
## Technology
24
-
To be completed.
44
+
This API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).
45
+
46
+
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.
47
+
48
+
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).
49
+
50
+
You do not need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules.
51
+
In particular:
52
+
- resource names are capitalised and singular, for example `/Patient` not `/patients`
53
+
- array names are singular, for example `line` not `lines` for address lines
54
+
- data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an `extension` object
55
+
56
+
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.
57
+
25
58
### Open source
26
-
To be completed.
59
+
You might find the following [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) resources useful:
| Validated Relationships FHIR API | Source code for the API proxy, sandbox and specification. | [GitHub repo](https://github.com/NHSDigital/validated-relationships-service-api) |
64
+
| 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) |
65
+
| 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/) |
66
+
67
+
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).
68
+
69
+
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).
70
+
27
71
## Network access
28
-
To be completed.
72
+
This API is available on the internet.
73
+
74
+
For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).
75
+
29
76
## Security and authorisation
30
-
To be completed.
77
+
78
+
This API has one access mode:
79
+
- patient access
80
+
81
+
### Patient access
82
+
Use this access mode if you wish to perform the following on behald of a user:
83
+
* get the patients a person can act on behalf of (proxy for)
84
+
85
+
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.
86
+
87
+
The end user must be:
88
+
* a patient who receives health and social care or makes use of NHS services
89
+
* strongly authenticated, using [NHS login](https://digital.nhs.uk/services/nhs-login)
90
+
91
+
To use this access mode, use one of the following security patterns:
|[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. |
96
+
|[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. |
| Integration test | `https://int.api.service.nhs.uk/validated-relationships/FHIR/R4/` |
105
+
| Production | `https://api.service.nhs.uk/validated-relationships/FHIR/R4/` |
106
+
107
+
### Sandbox testing
108
+
TO BE COMPLETED
109
+
110
+
### Integration testing
111
+
TO BE COMPLETED
112
+
113
+
### Production smoke testing
114
+
TO BE COMPLETED
115
+
33
116
## Onboarding
34
117
To be completed.
35
118
## Errors
36
-
To be completed.
119
+
We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:
120
+
121
+
* 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
122
+
* 400 to 499 if it failed because of a client error by your application
123
+
* 500 to 599 if it failed because of an error on our server
124
+
125
+
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.
126
+
37
127
38
128
contact:
39
129
name: 'Validated Relationships Service API Support'
| 429 | `THROTTLED` | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
0 commit comments