Properties of a REST API method document

Properties of a REST API method document

Purpose

...

1. Save new healthcare service in healthcare_services table (PRM DB) with data from request and additional fields:

   1. id = autogenerated;

   2. legal_entity_id = client_id from access token;

   3. status = ACTIVE;

   4. is_active = true;

   5. inserted_at = now();

   6. inserted_by = user_id from access token;

   7. updated_at = now();

   8. updated_by = user_id from access token;

Configuration parameters

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

Dictionaries

• PROVIDING_CONDITION

• SPECIALITY_TYPE

• HEALTHCARE_SERVICE_CATEGORIES

• HEALTHCARE_SERVICE_PHARMACY_DRUGS_TYPES

Input parameters

...

parameters

Request structure

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

Description of the REST API request structure, example

{
  "division_id": "8be63914-a278-470b-b868-1af5b9087332",
  "speciality_type": "FAMILY_DOCTOR",
  "providing_condition": "OUTPATIENT",
  "license_id": "cdcf456b-e235-4850-9f00-27cc3453d346",
  "category": {
    "coding": [
      {
        "system": "HEALTHCARE_SERVICE_CATEGORIES",
        "code": "MSP"
      }
    ]
  },
  "type": {
    "coding": [
      {
        "system": "HEALTHCARE_SERVICE_PHARMACY_DRUGS_TYPES",
        "code": "SALE"
      }
    ]
  },
  "comment": "Новий сервіс",
  "coverage_area": [
    "2c0110a9-0bea-4b16-af8e-6e2e149a5bfc"
  ],
  "available_time": [
    {
      "days_of_week": [
        "mon"
      ],
      "all_day": true,
      "available_start_time": "08:30:00",
      "available_end_time": "19:00:00"
    }
  ],
  "not_available": [
    {
      "description": "Санітарний день",
      "during": {
        "start": "during": {"2018-08-02T10:45:16.000Z",
         "startend": "2018-08-02T1002T11:4500:1600.000Z",
      }
    }
   "end": "2018-08-02T11:00:00.000Z"
      }
    }
  ]
}

Headers

...

Key

...

Value

...

Mandatory

...

Description

...

Example

...

Content-Type

...

application/json

...

M

...

Тип контенту

...

Content-Type:application/json

...

Authorization

...

Bearer c2778f3064753ea70de870a53795f5c9

...

M

...

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

...

Authorization:Bearer c2778f3064753ea70de870a53795f5c9

...

API-key

...

uXhEczJ56adsfh3Ri9SUkc4en

...

API-key:uXhEczJ56adsfh3Ri9SUkc4en

...

]
}

Headers

Request data validation

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 = 'healthcare_service:write')

  • return 403 (“Your scope does not allow to access this resource. Missing allowances: healthcare_service:write”) 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

• Validate request using JSON schema

  • in case of error - return 422

...

• Get division by $.division_id. Check that division exists in PRM DB

  • in case of error - return 422 (“Division does not exist”)

• Get division by $.division_id. Check that division status = ‘ACTIVE’

  • in case of error - return 422 (“Division should be active”)

• Get division by $.division_id. Check that division.legal_entity_id = legal entity id from access token

  • in case of error - return 422 (“Division should belong to your legal entity”)

Validate category

• Check that category is a value from HEALTHCARE_SERVICE_CATEGORIES dictionary

  • in case of error - return 422 (“value is not allowed in enum“)

• Extract legal entity id from access token. Check that category exists in HEALTHCARE_SERVICE_<legal_entity_type>_CATEGORIES chart parameret.

  • in case of error - return 422 (“Healthcare service category is not allowed for legal entity type”)

• Get HEALTHCARE_SERVICE_<$.category>_LICENSE_TYPE chart parameter.

  • If it exists and is not empty, check that $.license_id exists and is not null in request

    • in case of error - return 422 (“Healthcare service category must have linked license”)

  • If it does not exist or exists and is empty, check that $.license_id does not exist in request

    • in case or error - return 422 (“License must not be submitted for healthcare service category”)

Validate speciality type

• Get HEALTHCARE_SERVICE_SPECIALITY_TYPE_FIELD_REQUIRED_FOR_CATEGORIES chart parameter. If $.category is in chart param, check that $.speciality_type is passed in request

  • in case of error - return 422

• Check that speciality type is a value from SPECIALITY_TYPE dictionary

  • in case of error - return 422 (“value is not allowed in enum")

Validate providing condition

• Extract legal entity id from access token. Check that providing condition in request is allowed for legal entity type according to Configurations for Healthcare services

  • in case of error - return 422 (“value is not allowed in enum")

Validate type

• Get HEALTHCARE_SERVICE_TYPE_FIELD_REQUIRED_FOR_CATEGORIES chart parameter. If $.category is in chart param, check that $.type is passed in request

  • in case of error - return 422

• Check that type is a value from HEALTHCARE_SERVICE_<$.category>_TYPES dictionary

  • in case of error - return 422 (“value is not allowed in enum”)

Validate license

• Get license by $.license_id and legal_entity_id from access token. Check that license exists in PRM DB

  • in case of error - return 422 (“License for legal entity does not exist”)

• Get license by $.license_id. Check that license is not expired (is_active = true and (expiry_date>=now() or expiry_date is null))

  • in case or error - return 422 (“License is expired”)

• Get license by $.license_id. Check that license type equals to a value from HEALTHCARE_SERVICE_<$.category>_LICENSE_TYPE chart parameter

  • in case of error - return 409 (“License type does not match healthcare service category”)

Validate constraint

• Check that there is no another record with the same healthcare service, division_id, speciality type and providing condition

  • in case of error - return 409 (“division_id, speciality_type and providing_condition combination should be unique”)

• Check that there is no another record with the same healthcare service, division_id, category and type

  • in case of error - return 409 (“division_id, category and type combination should be unique”)

• Check that there is no another record with the same healthcare service, division_id and category = ‘PHARMACY’

  • in case of error - return 409 (“division_id and category = PHARMACY combination should be unique”)

Validate available time

• If $.all_day = true, check that fields available_start_time and available_end_time does not exist in request

  • in case of error - return 422 (“Should not be present when all_day = true“)

• If all_day = false, check that fields available_start_time and available_end_time exist in request

  • in case of error - return 422 (“Should be present when all_day = false“)

...

• Check that each object in not_available array has a valid period in $.not_available.during. during.end must be greater than during.start

  • in case of error - return 422 (“Should be greater then start“)

Processing

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

Response structure examples

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

Description of the REST API response structure, example

{
  "meta": {
    "code": 201,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": {
    "id": "7c3da506-804d-4550-8993-bf17f9ee0402",
    "division_id": "8be63914-a278-470b-b868-1af5b9087332",
    "legal_entity_id": "483af06f-d4c6-4c9e-8d9b-680b5ef7270d",
    "license_id": "cdcf456b-e235-4850-9f00-27cc3453d346",
    "speciality_type": "FAMILY_DOCTOR",
    "providing_condition": "OUTPATIENT",
    "category": {
      "coding": [
        {
          "system": "HEALTHCARE_SERVICE_CATEGORIES",
          "code": "MSP"
        }
      ]
    },
    "type": {
      "coding": [
        {
          "system": "HEALTHCARE_SERVICE_PHARMACY_DRUGS_TYPES",
          "code": "SALE"
        }
      ]
    },
    "status": "ACTIVE",
    "comment": "Заведено помилково",
    "coverage_area": [
      "2c0110a9-0bea-4b16-af8e-6e2e149a5bfc"
    ],
    "available_time": [
      {
        "days_of_week": [
          "mon"
        ],
        "all_day": true,
        "available_start_time": "08:30:00",
        "available_end_time": "19:00:00"
      }
    ],
    "not_available": [
      {
        "description": "Санітарний день",
        "during": {
          "start": "2018-08-02T10:45:16.000Z",
          "end": "2018-08-02T11:00:00.000Z"
        }
      }
    ],
    "licensed_healthcare_service": {
      "status": "ACTIVE",
      "updated_at": "2022-04-20T19:14:13Z"
    },
    "is_active": true,
    "inserted_at": "2017-04-20T19:14:13Z",
    "inserted_by": "e1453f4c-1077-4e85-8c98-c13ffca0063e",
    "updated_at": "2017-04-20T19:14:13Z",
    "updated_by": "2922a240-63db-404e-b730-09222bfeb2dd"
  }
}

...

Post-processing processes

Description of actions performed on data after processing

Technical modules where the method is used

List of pages describing technical modules where the method is used

...