REST API method / Метод REST API (настанова) (remove the link block before publishing the REST API method / Метод REST API (настанова) (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

...

1. Only authenticated and authorized user with employee_type from the list ofCARE_PLAN_AUTHOR_EMPLOYEE_TYPES_ALLOWED
   config with appropriate speciality pointed in CARE_PLAN_<category>_SPECIALITIES_ALLOWEDconfig can create a Care plan.

2. Care plan can be created from MSP, PRIMARY_CARE or OUTPATIENT legal entity.

3. Care plan can be created for persons and prepersons.

4. Care plan should be signed with DS.

5. Care plan creates in async way as all MEs.

6. Activities are added to a Care plan using Create Care Plan activity method. Thus, Care plan is being initially created without activities.

...

PROVIDING_CONDITION

Input parameters

Description of input parameters

Request structure

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

Description of the REST API request structure, example

{
  "signed_data": "ew0KICAicGVyaW9kIjogew0KIC..."
}

...

1. Extract user_id from token. Check that author belongs to one of the user’s employee.

   1. in case of error - return 422 ('User is not allowed to create care plan for the employee')

2. Check that author is an active and approved employee and related to the legal entity (client_id from token).

   1. in case of error - return 403 ('Access denied')

3. Check author’s employee type:

   1. for employees with employee_type from CARE_PLAN_AUTHOR_ROLE_CHECK_EMPLOYEE_TYPESconfig:

      1. Сheck it has at least one employee role that:

         1. is active and has active status

         2. refers to healthcare service with providing_conditions=$.terms_of_service value

            1. in case of error - return 422 ('Employee does not have active role that correspond to the submitted terms of service')

   2. If DOCTOR, then no additional validations needed

4. Check author’s speciality (speciality_officio == true) pointed in config for a corresponding care plan category.

   1. in case of error - return 409 (“Invalid employee speciality”)

...

1. Check the value is valid reference on encounter resource

   1. Check encounter is active (status is not entered_in_error)

      1. in case of error - return 422 ('Encounter in "entered_in_error" status can not be referenced')

   2. Check encounter belongs to patient ($.subject)

      1. in case of error - return 422 ('Encounter with such id is not found')

   3. Check that encounter diagnosis is not empty in $.encounter.diagnosis

      1. in case of error - return 422 ('Encounter without diagnosis can not be referenced')

2. Validate primary diagnosis Condition in the Encounter:

   1. Check condition codes is in allowed condition code list for the care plan’s category (chart variables in config: for employee types: SPECIALIST, DOCTOR and MED_COORDINATOR)

      1. in case of error - return 422 ('Primary diagnosis condition code and care plan category mismatch')

   2. Check the condition system/codes has strict match with the value in the Addresses field

      1. in case of error - return 422 ('Primary diagnosis condition codes do not match with codes in addresses') in case condition code in addresses is not the same as in the encounter diagnosis.

3. Validate Episode related to the Encounter:

   1. exists

      1. in case of error - return 422 ('Encounter refers to episode that does not exist')

   2. is active

      1. in case of error - return 422 ('Encounter refers to episode that is not active')

   3. it’s managing organization matches with author’s legal entity (client_id)

      1. in case of error - return 422 ('Encounter is from another legal entity')

...

1. Check that there is values from a dictionary PROVIDING_CONDITION.

   1. in case of error - return 422 ('value is not allowed in enum')

2. Check submitted value:

   1. define allowed terms_of_service for employee_type using a set of chart variables CARE_PLAN_<employee_type>_TERMS_OF_SERVICE_ALLOWED

      1. in case terms_of_service not allowed for the employee_type - return 422 ('Not allowed for <employee type>')

...

1. Check that $.period.start >= encounter.date (OR encounter.period.start)

   1. in case of error and encounter.period.start - return 422 ('Care plan start date must be greater or equal than Encounter period start')

   2. in case of error and encounter.date - return 422 ('Care plan start date must be greater or equal than Encounter start date')

2. Check that $.period.end >= $.period.start

   1. in case of error - return 422 ('End date must be greater than or equal the start date')

...

Response structure examples

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

Description of the REST API response structure, example

{
  "data": {
    "id": "90a9e15b-b71b-4caf-8f2e-ff247e8a5600",
    "based_on": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "care_plan"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    },
    "part_of": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "care_plan"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    },
    "category": {
      "coding": [
        {
          "system": "eHealth/care_plan_categories",
          "code": "diabetics"
        }
      ]
    },
    "title": "Diabetics health plan",
    "description": "Some description of the care plan",
    "period": {
      "start": "2018-08-02T10:45:16.000Z",
      "end": "2018-08-02T11:00:00.000Z"
    },
    "supporting_info": [
      {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "episode_of_care"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        }
      }
    ],
    "note": "Some notes",
    "intent": "order",
    "encounter": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "encounter"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    },
    "addresses": [
      {
        "coding": [
          {
            "system": "eHealth/ICD10_AM/condition_codes",
            "code": "E11.9"
          }
        ]
      }
    ],
    "author": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "employee"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    },
    "contributor": [
      {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "employee"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        }
      }
    ],
    "terms_of_service": {
      "coding": [
        {
          "system": "PROVIDING_CONDITION",
          "code": "INPATIENT"
        }
      ]
    },
    "inform_with": {
      "auth_method_id": "cc949559-5dfe-420f-ac05-065e443b2cc6"
    },
    "status": "active",
    "subject": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "patient"
            }
          ]
        },
        "value": "7c3da506-804d-4550-8993-bf17f9ee0403"
      }
    },
    "status_history": [
      {
        "status": "active",
        "status_reason": {
          "coding": [
            {
              "system": "eHealth/care_plan_cancel_reasons",
              "code": "some code"
            }
          ]
        },
        "inserted_at": "2018-08-02T10:45:16.000Z",
        "inserted_by": "e1453f4c-1077-4e85-8c98-c13ffca0063e"
      }
    ],
    "requisition": "0123-4567-89AB-CEIK",
    "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"
  },
  "meta": {
    "code": 201,
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  }
}

{
  "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

...

Response code

...

HTTP Status code

...

Message

...

Internal name

...

Description

...

Базові

...

codes

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