Properties of a REST API method document

...

...

Document type

...

Метод REST API

...

Guideline ID

...

GUI-0011

...

Author

...

@

...

Document version

...

1

...

Document status

...

DRAFT

...

Date of creation

...

ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)

...

Date of update

...

ХХ.ХХ.ХХХХ (дата зміни версії)

...

Method API ID

...

API-001-001-001-0001

...

Microservices (namespace)

...

MPI

...

Component

...

Auth

...

Component ID

...

COM-001-001

...

Link на API-специфікацію

...

https://medicaleventsmisapi.docs.apiary.io/#reference/service-requests/manage-service-requests/use-service-request

...

Resource

...

{{host}}//api.ehealth.gov.ua/api/patients/id/encounter_package

...

Scope

...

Protocol type

...

Request type

...

Sync/Async

...

Public/Private

Purpose

Describe the purpose of the API method, add Key points (if necessary)

Logic

Description of the working algorithm of the API method and the interaction of services with each other add Service logic (if necessary)

Configuration parameters

Description of the configuration parameters that are used when processing a request in the system

Dictionaries

Provides a list of links to dictionaries that are available in Confluence

Input parameters

Description of input parameters

...

Input parameter

...

Mandatory

...

Type

...

Description

...

Example

...

composition_id

...

 M

...

String ($uuid) (path)

...

Composition object ID

...

 89678f60-4cdc-4fe3-ae83-e8b3ebd35c59

...

Request structure

See on API-specification (посилання на сторінку з API-специфікацією)

Description of the REST API request structure, example

...

...

Headers

...

Key

...

Value

...

Mandatory

...

Description

...

Example

...

Content-Type

...

application/json

...

M

...

Тип контенту

...

Content-Type:application/json

...

Authorization

...

Bearer c2778f3064753ea70de870a53795f5c9

...

M

...

Перевірка користувача

...

Authorization:Bearer c2778f3064753ea70de870a53795f5c9

...

Request data validation

Describe the process of checking the input data transmitted in the request for compliance with the given rules and restrictions set in the API

Processing

A list of processes related to receiving, changing or transmitting data according to the logic defined in the REST API

Response structure examples

Description of the REST API response structure, example

...

...

HTTP status codes

...

Response code

...

HTTP Status code

...

Message

...

Internal name

...

Description

...

Базові

...

1000

...

404

...

Composition not found

...

COMPOSITION_NOT_FOUND_404

...

Не знайдено медичний висновок

...

401

...

Unauthorized

...

Помилка підтвердження

...

Специфічні

...

422

...

Only for active MPI record can be created medication request!

Post-processing processes

...

Properties of a REST API method document

Purpose

N/A

Logic

...

Service logic

1. Update service request attributes

   1. Set Medical Events DB: 

      1. If used_by_employee exists in requests set service_requests[<id>].used_by_employee = Request: $.used_by_employee

      2. set service_requests[<id>].used_by_legal_entity = Request: $.used_by_legal_entity

   2. if medical program exists in request

      1. Set Medical Events DB: service_requests[<id>].medical_program = Request: $.medical_program.identifier.value

2. Fill program_processing_status_history

3. Change program_processing_status to `in_queue`

4. Change program_processing_status to `in_progress`

5. Fill used_by_legal_entity_history

6. Fill used_by_employee_history

Configuration parameters

N/A

Dictionaries

N/A

Input parameters

Request structure

See on API-specification

{
  "used_by_employee": {
    "identifier": {
      "type": {
        "coding": [
          {
            "system": "eHealth/resources",
            "code": "employee"
          }
        ]
      },
      "value": "d5a5d991-0bf7-476f-b3cf-bec73f044b2e"
    }
  },
  "used_by_legal_entity": {
    "identifier": {
      "type": {
        "coding": [
          {
            "system": "eHealth/resources",
            "code": "legal_entity"
          }
        ]
      },
      "value": "c5a6d991-0bf7-476f-b3cf-bec83f044b2a"
    }
  },
  "used_by_division": {
    "identifier": {
      "type": {
        "coding": [
          {
            "system": "eHealth/resources",
            "code": "division"
          }
        ]
      },
      "value": "c5a6d991-0bf7-476f-b3cf-bec83f044b2a"
    }
  },
  "program": {
    "identifier": {
      "type": {
        "coding": [
          {
            "system": "eHealth/resources",
            "code": "medical_program"
          }
        ]
      },
      "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
    }
  

Headers

Headers

Request data validation

Authorize

• Verify the validity of access token

  • return 401 ('Unauthorized') in case of validation fails

• Verify that token is not expired

  • in case of error - return 401 ('Unauthorized')

• Check user scopes in order to perform this action (scope = 'service_request:use')

  • Return 403 ('Invalid scopes') in case of invalid scope(s)

• If BLOCK_UNVERIFIED_PARTY_USERS is true, then check party's data match following condition: verification_status != NOT_VERIFIED or (verification_status = NOT_VERIFIED and updated_at <= current_date - UNVERIFIED_PARTY_PERIOD_DAYS_ALLOWED):

  •  in case not match - return 403 ("Access denied. Party is not verified")

  • Validate request using JSON Schema

    Return 422 with the list of validation errors in case validation fails

Validate legal entity

• Check legal entity type: it has to be in me_allowed_transactions_le_types config parameter, has status = active 

  • in case of error return 409 "Action is not allowed for the legal entity"

Validate transition

Only active and unused (released) service request with a specified medical program can be used

1. Get service request by ID

2. Service request contains medical program

   1. $.program is NOT NULL

      1. in case of error return 409 "Service request without a program can not be used"

3. Service request must be valid by the expiration date

   1. $.expiration_date should be greater than or equal to current date

      1. in case of error return 409 "Service request is expired"

4. Service request must be active

   1. $.status  == "active"

      1. in case of error return 409 "Can't use inactive service request"

5. Service request must be unused

   1. $.used_by_legal_enity is empty object

      1. in case of error return 409 "Service request is already used"

6. Service request is not completed according to program_processing_status

   1. in case of error return 409 "Service request is already completed"

Validate program

1. Validate program is an existing service program (type=service)

   1. in case not found or is_active==false return 422  "Program not found"

   2. in case type!= service return 409 "Invalid program type"

2.  Service(or service_group) is an active member of the program

   1. Select request_allowed, is_active from PRM.program_services where service_id(or group_id) == $.signed_content.code.identifier.value and program_id=$.program.identifier.value

      1. if not found or is_active==false return 409 "Service is not included in the program"

3. Qualify service request

   1. if medical program exists in request 

      1.  invoke qualify for medical program in in use request

   2. if not exists

      1. invoke qualify in SR, if it is in SR

Validate request

1. Get token metadata

   1. Extract user_id, client_id, client_type

2. Ensure that employee belongs to client

   1. $.used_by_employee.identifier.type.coding[*].system == "eHealth/resources"

   2. $.used_by_employee.identifier.type.coding[*].code == "employee"

   3. $.used_by_employee.identifier.value must belong to client_id (prm.employees.legal_entity_id == :client_id)

      1. in case of error return 422 "You can assign service request only to employee within your legal entity"

3. Check employee_type:

   1. in $.used_by_employee field validate employee_type:

      1. if service_request.category="laboratory_procedure", "diagnostic_procedure" OR "procedure" check employee_type == DOCTOR, SPECIALIST, ASSISTANT OR LABORANT

      2. else  employee_type == DOCTOR OR SPECIALIST

         1. in case of error, return 422 "Invalid employee type"

4. Validate used_by_legal_entity is a current legal_entity

   1. $.used_by_legal_entity.identifier.value==token.client_id

      1. in case of error return 409 "You can assign service request only to your legal entity"

5. Validate used_by_division

   1. if SR.category = hospitalization

      1. validate used_by_division is sent, in case error return 422, "Division is mandatory for $category category"

      2. validate used_by_division.legal_entity_id = used_by_legal_entity_id

   2.  Is SR.category = transfer_of_care

      1. validate used_by_division is sent, in case error return 422, "Division is mandatory for $category category"

      2. Validate $division.legal_entity_id = SR.Performer, in case error return 422, "Patient is transferred to another legal entity"

Validate reuse allowed

If service request has already been used by legal entity and another legal entity wants to reuse it, then check the period for the prohibition of reuse has passed:

1. If used_by_legal_entity is different from current legal_entity:

   1. Get the latest entity from used_by_legal_entity_history.

   2. Compare that the difference (in minutes) between the current datetime and inserted_at of the latest entity is greater than the SERVICE_REQUEST_REUSE_AFTER_MINUTES chart param. Сonsider that the SERVICE_REQUEST_REUSE_AFTER_MINUTES is equal to zero minutes if it is empty or absent.

      1. in case it less - return 409 error “Reuse is temporarily blocked. It will be allowed after <SERVICE_REQUEST_REUSE_AFTER_MINUTES - difference> minutes“

Посилання на додаткову /wiki/spaces/CSI/pages/16871063599

Processing

N/A

Response structure examples

See on API-specification

{
  "data": {
    "status": "pending",
    "eta": "2018-08-02T10:45:16.000Z",
    "links": [
      {
        "entity": "job",
        "href": "/Jobs/NBXk9EyErUZv1RhXgyvgg"
      }
    ]
  },
  "meta": {
    "code": 202,
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  }

HTTP status codes

Post-processing processes

N/A

Technical modules where the method is used

List of pages describing technical modules where the method is used

...