Purpose*
Необхідно зазначити призначення методу.
Наприклад: This method allows to receive active person declarations issued by the current legal entity (based on access_token)This WS allows to get detailed episode info from Admin panel.
Specification*
Link |
| Посилання на Apiary або Swagger |
Resource |
| Посилання на ресурс, наприклад: /api/persons/create |
Scope |
| Scope для доступу |
Components |
| Зазначається перелік бізнес компонентів, які використовують цей метод, наприклад: ePrescription |
Microservices |
| Перелік мікросервісів, які використовує метод API, наприклад: Auth, ABAC |
Protocol type | Тип протоколу, який використовується запитом, наприклад: SOAP | REST | |
Request type | Тип запиту API, наприклад: GET, POST, PATCH… | |
Sync/Async |
| Метод є синхронним чи асинхронним? |
Public/Private/Internal | Потрібно зазначити тип методу за ступенем доступності |
Logic*
...
Потрібно по пунктах описати логіку методу API або додати діаграму
Preconditions
Які передумови мають бути виконані системою/користувачем. Наприклад:
створений запис в MedicationRequest;
рецепт відпущений (COMPLETED)
Global and configurable parameters
Потрібно вказати глобальні та конфігураційні параметри.
Наприклад:
...
Variable
...
Values
...
Description
...
CARE_PLAN_<category>_ICD10_AM_CONDITIONS_ALLOWED
...
Values that matches with dictionaryeHealth/ICD10_AM/condition_codes
Example: “E10.32, E11.92”
...
(Example: CARE_PLAN_CLASS_1_ICD10_AM_CONDITIONS_ALLOWED)
Input parameters
Потрібно вказати вхідні параметри запиту. Наприклад, для GET /patients/composition/job/{{asyncJobId}} вхідний параметр:
...
Input parameter
...
Values
...
Type
...
Description
...
Example
...
asyncJobId
...
...
String
...
Async Job Object ID
...
Filters
Потрібно вказати фільтри. Наприклад, для GET /api/medication_requests/{{id}}/dispenses?status=PROCESSED фільтр:
...
Filter
...
Values
...
Type
...
Description
...
Example
...
status
...
...
String
...
Optional
...
PROCESSED
Dictionaries
Потрібно вказати довідники, які використовує метод API
Request structure*
See on Apiary
Example:
...
| title | Request example |
|---|
Authorize*
...
Get episode by id and patient_id
Render detailed episode data according to schema
Key points
This is a graphQl query used in Administration panel only
Only authenticated and authorized NHS employee with appropriate scope can get episode details.
Query returns single episode by person (mpi id) and episode identifier.
Filtration with forbidden group items is worked here. So NHS employee should have an approval from patient to see an episode with forbidden elements.
Query should be invoked only if Justification for monitoring exists for current user and corresponding patient (ABAC rule_-2).
Request structure*
API paragraph not found
Specification
| Expand | ||
|---|---|---|
| ||
|
Authorize*
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 scopes in order to perform this action (scope = 'episode:practical_monitor')
return 403 (“Your scope does not allow to access this resource. Missing allowances: episode:practical_monitor”) in case of invalid scope(s)
Check user has access to resource according to @rule_-2 in ABAC
return 403 (“Access denied. Justification required“) in case of error
Request to process the request using a token in the headers
Headers*
Наприклад:
Content-Type:application/json
Authorization:Bearer c2778f3064753ea70de870a53795f5c9
api-key:uXhEczJ56adsfh3Ri9SUkc4en
API paragraph not found
Request data validation*
Валідація даних
Наприклад:
Validate request using JSON schema
In case validation failed - generate 422 error
...
| title | JSON schema |
|---|
Processing*
Потрібно описати процеси, які відбуваються з даними
1. Using global parameters
Потрібно викликати глобальні параметри (Global parameters), щоб отримати наведені нижче параметри
Response structure*
See on Apiary
Example:
...
| title | Response example |
|---|
Post-processing processes*
Що має відбутися в ЦБД після опрацювання та відправлення відповіді, тощо
HTTP status codes*
...
HTTP status code
...
Message
...
What caused the error
...
...
...
...
...
...
Backward compatibility
...
Validate legal entity
Extract client_id from token.
Check client scopes in order to perform this action (scope = 'episode:practical_monitor')
in case of error - return 403 (“Your scope does not allow to access this resource. Missing allowances: episode:monitor”)
Check legal entity status (status = ACTIVE)
In case of error - return 409 ('client_id refers to legal entity that is not active')
Validate request
Check required
personIdsubmitted.return 404 (“not found“) in case not exist
Check required episode
Idsubmitted.return 404 (“not found“) in case not exist or not related to person
return 403 (“Access denied“) in case episode has forbidden group items. Take into account approvals granted to NHS employee on forbidden groups (look at Medical Events filtration by Forbidden groups for details)
Processing*
API paragraph not found
Response structure*
API paragraph not found
Post-processing processes*
API paragraph not found
HTTP status codes*
API paragraph not found