Properties of a REST API method document

Purpose

Describe This method checks the purpose possibility 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 using the direction according to the program.

Logic

https://e-health-ua.atlassian.net/wiki/x/CwPGIg

Configuration parameters

N/A

Dictionaries

N/A

Input parameters

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

{
  "programs": [
    {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "medical_program"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    }
  ]
}

Headers

Headers

Request data validation

Authorize

Request to process the request using a token in the headers

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

  1. Return (403, 'invalid scopes') in case of invalid scope(s)Processing

  2. Validate request using JSON Schema

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

Validate request

1. legal entity(client_id)

   1. Check legal_entity.type in me_allowed_transactions_le_types config parameter and legal_entity.status = ACTIVE 

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

2. service request

   1. validate SR.program_processing_status in (new,In Queue,In Progress)

      1. in case error return 409, “service request has wrong status“

   2. validate SR.status = Active

      1. in case error return 409, “service request has wrong status“

   3. If SR.based_on is present:

      1. Verify submitted Activity:

         1. It has scheduled, in_progress status

            1. in case of error return 409, "Invalid activity status")

         2. if quantity was set, then validate remaining_quantity greater then zero:

            1. in case of error return 409, "The number of available services according to the care plan activity has been exhausted"

      2. Verify Care plan:

         1. It should be in active status

            1. in case of error return 409, "Care plan is not active"

         2. Care plan's period end (if exist) should be greater than current date or equal.

            1. in case of error return 409, “Care plan expired“

   4. Validate remaining quantity of services is still available:

      1. If SR has quantity:

         1. Validate remaining_quantity within SR is greater then zero

            1. in case of error return 409 (The number of available services according to the service request has been exhausted)

      2. If SR has no quantity, but it is based on activity with quantity:

         1. Validate remaining_quantity within Activity is greater then zero

            1. in case of error return 409 (The number of available services according to the care plan activity has been exhausted)

3. program

   1. For each program validate it is an existing service program with type=service

      1. in case not found or is_active==false write result in Data collection according to apiary

      2. in case type!= service write result in Data collection according to apiary - "Invalid program type"

   2. For each program validate that service(or service_group) is an active member of the program

      1. Select 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 write result in Data collection according to apiary - "Service is not included in the program"

Response structure examples

See on API-specification

{
  "meta": {
    "code": 200,
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": [
    {
      "program_id": "59781de0-2e64-4359-b716-bcc05a32c10f",
      "program_name": "Fee-For-Service",
      "status": "INVALID",
      "rejection_reason": "Service is not included in the program"
    }
  ]
}

Prepare & return response data structure

1. For each program in array prepare response

2. If it is any or some errors from validations return “NOT VALID“ with error msg

HTTP status codes

Post-processing processes

Description of actions performed on data after processingN/A

Technical modules where the method is used

List of pages describing technical modules where the method is used

...