/wiki/spaces/EN/pages/17591304241 (remove the link block before publishing the document)
Properties of a REST API method document
Document type | Метод REST API |
|---|---|
Document title | [DRAFT] Get Specimen by search params [API-007-012-001-0494] |
Guideline ID | GUI-0011 |
Author | @ |
Document version | 1 |
Document status | DRAFT |
Date of creation | ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD) |
Date of update | ХХ.ХХ.ХХХХ (дата зміни версії) |
Method API ID | API-007-012-001-0494 |
Microservices (namespace) | ABAC |
Component | Specimen |
Component ID | COM-007-012 |
Link на API-специфікацію | |
Resource | {{host}}/api/patients/patient_id/specimens |
Scope | specimen:read |
Protocol type | REST |
Request type | GET |
Sync/Async | Async |
Public/Private | Public |
Purpose
This WS allows to get a list of Specimens in patient context. Also, this list can be filtered using search parameters.
Key points
Only authenticated and authorized employee with appropriate scope can get a list of Specimen.
Method returns a list of Specimen that belongs to the specified patient.
List can be filtered by search params.
ABAC rules are used here
Logic
Service returns all Specimens related to the patient filtered by submitted parameters:
Get all Specimens by subject from specimens collection (MongoDB)
Filter list above by submitted search parameters
Render a response according to specification with a list of found Specimen entities.
Configuration parameters
Dictionaries
Input parameters
Input parameter | Mandatory | Type | Description | Example | |
|---|---|---|---|---|---|
| 1 | patient_id |
| String | Unique patient identifier |
|
| 2 |
|
|
|
|
|
Request structure
See on API-specification
Headers
Request data validation
Authorization
Verify the validity of access token
in case of error - return 401 “Invalid access token” in case of validation fails
Verify that token is not expired
in case of error - return 401 “Invalid access token”
Check user and client scopes in order to perform this action (scope = 'specimen:read')
return 403 “Your scope does not allow to access this resource. Missing allowances: specimen:read” in case of invalid scope(s)
Access to the resource is also managed by ABAC module
Validate Patient
Get Patient identifier from the URL
Check it exists in DB
Return 404 ('not found') in case of error
Search params
All search params are optional. Search with a few params executes according to the logical AND rule.
status
filter list by specimen.status
type
filter list by specimen.type.coding[*].code
registered_by.
filter list by specimen.registered_by.identifier.value
collected_from
In depend on what is set - filter by specimen.collection.collected_date_time or specimen.collection.collected_period field. Do not take time into account.
filter list by $.collected_from <= collected_date_time
filter list by $.collected_from <= collected_period.end
collected_to
In depend on what is set - filter by specimen.collection.collected_date_time or specimen.collection.collected_period field. Do not take time into account.
filter list by $.collected_to >= collected_date_time.
filter list by $.collected_to >= collected_period.start
container_identifier
filter list by specimen.container[*].identifier
container_type
filter list by specimen.container[*].type
parent
filter list by specimen.parent.identifier.value
request
filter list by specimen.request[*].identifier.value
encounter
filter list by specimen.context[*].identifier.value
Processing
N/A
Response structure examples
See on API-specification
HTTP status codes
Response code | HTTP Status code | Message | Internal name | Description | |
|---|---|---|---|---|---|
| 1 | Базові | ||||
| 2 |
| 401 | Invalid access token |
|
|
| 3 |
| 403 | Your scope does not allow to access this resource. Missing allowances: specimen:read |
|
|
| 4 | 404 | not found | |||
Post-processing processes
N/A