FHIR Get Structured Record API: Difference between revisions
No edit summary |
No edit summary |
||
| Line 2: | Line 2: | ||
The Discovery FHIR CareConnect $getstructuredrecord API uses a secure authentication and authorisation service. This uses recommended standards for identity and access management, using OpenID Connect and OAuth 2.0 methods, and also includes an additional security layer, where DDS checks it’s internal User Management service to ensure that each user is authorised with the necessary role based access profiles to use each particular application. This allows for tokens and user access to be centrally managed and revoked within the DDS User Manager application. | The Discovery FHIR CareConnect $getstructuredrecord API uses a secure authentication and authorisation service. This uses recommended standards for identity and access management, using OpenID Connect and OAuth 2.0 methods, and also includes an additional security layer, where DDS checks it’s internal User Management service to ensure that each user is authorised with the necessary role based access profiles to use each particular application. This allows for tokens and user access to be centrally managed and revoked within the DDS User Manager application. | ||
Two API calls are used for | Two API calls are used for the FHIR CareConnect $getstructuredrecord API: | ||
* Authenticate | * Authenticate | ||
| Line 8: | Line 8: | ||
=== Authenticate === | === Authenticate === | ||
Authenticate the client identity by passing in client credentials to receive an access token for the API. | |||
https://devauthentication.discoverydataservice.net/authenticate/$gettoken | https://devauthentication.discoverydataservice.net/authenticate/$gettoken | ||
| Line 18: | Line 20: | ||
} | } | ||
</syntaxhighlight>userName and password | </syntaxhighlight>userName and password can be requested by contacting the Learning Health Solutions Helpdesk at https://learning-health.co.uk/. | ||
This returns an authorisation access_token in this JSON reply, or a 404 HTTP Not Found response if the user is not recognised.<syntaxhighlight lang="json"> | This returns an authorisation access_token in this JSON reply, or a 404 HTTP Not Found response if the user is not recognised.<syntaxhighlight lang="json"> | ||
| Line 32: | Line 34: | ||
} | } | ||
</syntaxhighlight>An access token can also be retrieved using the refresh_token value, once the user's identity has been authenticated using the above call. | |||
Passing this JSON POST body (no header required)<syntaxhighlight lang="json"> | |||
{ | |||
"grantType": "refresh_token", | |||
"clientId": "information-manager", | |||
"userName": "", | |||
"password": "<access_token_value>" | |||
} | |||
</syntaxhighlight> | </syntaxhighlight> | ||
=== Authorise/GetRecord === | |||
Retrieve a patient's structured care record as a FHIR bundle in the FHIR CareConnect STU3 format. See https://fhir.hl7.org.uk/ | |||
This call uses the access token from the authentication API to authorise the client's access to the API, which will return the FHIR bundle if the client is recognised and authorised to use this service. | |||
https://devfhir.discoverydataservice.net/patient/$getstructuredrecord | https://devfhir.discoverydataservice.net/patient/$getstructuredrecord | ||
| Line 66: | Line 81: | ||
</syntaxhighlight>'''Note:''' The patientDOB | </syntaxhighlight>'''Note:''' The patientDOB parameter is optional. | ||
Set the Authorization header in the REST POST call to the value of the '''access_token''' returned from the authentication API. | |||
'''Note:''' Access tokens expire if they are not used within 60 seconds. | '''Note:''' Access tokens expire if they are not used within 60 seconds. | ||
| Line 74: | Line 89: | ||
[[File:Options.png|border|600x600px]] | [[File:Options.png|border|600x600px]] | ||
If | If this API fails to authorise the access token against the Discovery identity and access management service, then an Unauthorised return value will be sent with a 401 HTTP Status (Unauthorized). | ||
Success will return the FHIR bundle for the patient specified in the query parameters. | Success will return the FHIR bundle for the patient specified in the query parameters. | ||
Revision as of 11:46, 29 May 2020
Introduction
The Discovery FHIR CareConnect $getstructuredrecord API uses a secure authentication and authorisation service. This uses recommended standards for identity and access management, using OpenID Connect and OAuth 2.0 methods, and also includes an additional security layer, where DDS checks it’s internal User Management service to ensure that each user is authorised with the necessary role based access profiles to use each particular application. This allows for tokens and user access to be centrally managed and revoked within the DDS User Manager application.
Two API calls are used for the FHIR CareConnect $getstructuredrecord API:
- Authenticate
- Authorise/GetRecord
Authenticate
Authenticate the client identity by passing in client credentials to receive an access token for the API.
https://devauthentication.discoverydataservice.net/authenticate/$gettoken
Passing this JSON POST body (no header required)
{
"grantType": "password",
"clientId": "information-manager",
"userName": "XXXXXXXXXXX",
"password": "XXXXXXXXXXXX"
}
userName and password can be requested by contacting the Learning Health Solutions Helpdesk at https://learning-health.co.uk/. This returns an authorisation access_token in this JSON reply, or a 404 HTTP Not Found response if the user is not recognised.
{
"access_token": "xxxxxxxx",
"refresh_token": "xxxxxxxxx",
"refresh_expires_in": 1800,
"not-before-policy": 1548863201,
"scope": "profile email",
"token_type": "bearer",
"session_state": "79b125f5-f062-4a4c-a5a6-b2fa4519e8ad",
"expires_in": 60
}
An access token can also be retrieved using the refresh_token value, once the user's identity has been authenticated using the above call. Passing this JSON POST body (no header required)
{
"grantType": "refresh_token",
"clientId": "information-manager",
"userName": "",
"password": "<access_token_value>"
}
Authorise/GetRecord
Retrieve a patient's structured care record as a FHIR bundle in the FHIR CareConnect STU3 format. See https://fhir.hl7.org.uk/
This call uses the access token from the authentication API to authorise the client's access to the API, which will return the FHIR bundle if the client is recognised and authorised to use this service.
https://devfhir.discoverydataservice.net/patient/$getstructuredrecord
Passing this JSON POST body
{
"meta": {
"profile": [
"https://fhir.hl7.org.uk/STU3/OperationDefinition/CareConnect-GetStructuredRecord-Operation-1"
]
},
"resourceType": "Parameters",
"parameter": [
{
"name": "patientNHSNumber",
"valueIdentifier": {
"system": "https://fhir.hl7.org.uk/Id/nhs-number",
"value": "5558526785"
}
},
{
"name": "patientDOB",
"valueIdentifier": {
"system": "https://fhir.hl7.org.uk/Id/dob",
"value": "1970-01-01"
}
}
]
}
Note: The patientDOB parameter is optional.
Set the Authorization header in the REST POST call to the value of the access_token returned from the authentication API.
Note: Access tokens expire if they are not used within 60 seconds.
If this API fails to authorise the access token against the Discovery identity and access management service, then an Unauthorised return value will be sent with a 401 HTTP Status (Unauthorized).
Success will return the FHIR bundle for the patient specified in the query parameters.
Workflow
