From c86b4999d798d1263f43c54ea3a60e9386bd3604 Mon Sep 17 00:00:00 2001 From: James Taylor Date: Fri, 19 Jan 2024 09:34:47 +0000 Subject: [PATCH] NPA-1711: add background API documentation --- .../validated-relationships-service-api.yaml | 144 ++++++++++++++---- 1 file changed, 117 insertions(+), 27 deletions(-) diff --git a/specification/validated-relationships-service-api.yaml b/specification/validated-relationships-service-api.yaml index 94fef86..5014b4e 100644 --- a/specification/validated-relationships-service-api.yaml +++ b/specification/validated-relationships-service-api.yaml @@ -6,45 +6,135 @@ 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: api.management@nhs.net 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: @@ -52,15 +142,15 @@ paths: 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