https://e-health-ua.atlassian.net/wiki/spaces/EN/pages/17591304241 (remove the link block before publishing the document)

• Properties of a REST API method document

• Purpose

• Logic

• Configuration parameters

• Dictionaries

• Input parameters

• Request structure

• Headers

• Request data validation

• Processing

• Response structure examples

• HTTP status codes

• Post-processing processes

• Technical modules where the method is used

Properties of a REST API method document

Purpose

This WS allows to get a list of Specimens in patient context. Also, this list can be filtered using search parameters.

Key points

1. Only authenticated and authorized employee with appropriate scope can get a list of Specimen.

2. Method returns a list of Specimen that belongs to the specified patient.

3. List can be filtered by search params.

4. ABAC rules are used here

Logic

RC._Процеси роботи зі зразком біоматеріалу | Отримання інформації Зразка при взаємодії з пацієнтом

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

N/A

Dictionaries

RC._Specimen dictionaries and configurable parameters_EN | Dictionaries

Input parameters

Request structure

See on API-specification

Headers

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

Post-processing processes

N/A

Technical modules where the method is used