-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
NPA-1711: add background API documentation
- Loading branch information
1 parent
d2a065d
commit 09687e6
Showing
1 changed file
with
117 additions
and
27 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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": | ||
|
|
@@ -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": | ||
|
|
@@ -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' | ||
|
|
||
|
|
@@ -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 | ||
|
|
@@ -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 | ||
|
|
||