Required parameters are marked with "*"

Якщо інформації по відповідному параметру немає, потрібно зазначити: “API paragraph not found”.

Purpose*

Необхідно зазначити призначення методу.

Наприклад: This method allows to receive active person declarations issued by the current legal entity (based on access_token)

Specification*

Project Name		COVID-certificate
Project abreviation		SVC
Developer		Розробник методу API. Наприклад, Edenlab
Project Manager		@Єлизавета Гессен-Дармштадська
Tech Lead		@Іоанн Воїнов
Product Owner		@Нікодім Святогорцев
Вusiness analyst		@Пантелеймон Нікомедійський
Status		APPROVED
Version		1.0
Date of release		22 Jun 2022
Link		Посилання на Apiary або Swagger
Resource		Наприклад: /api/persons/create
Scope		Зазначається потрібний scope
Components		Зазначається перелік бізнес компонентів, які використовують цей метод, наприклад: ePrescription
Microservices		Перелік мікросервісів, які використовує метод API. Наприклад: Auth, ABAC
Protocol type		Тип протоколу, який використовується запитом, наприклад: SOAP \| REST
Request type		Тип HTTP методу, який використовується запитом, наприклад: POST \| GET…
Sync/Async		Метод є синхронним чи асинхронним?

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”

Allowed diagnoses for specified care plan category. Diagnoses should match with eHealth/ICD10_AM/condition_codes dictionary, <category> - is a value from dictionary eHealth/care_plan_categories in uppercase

_{(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

Request structure*

See on Apiary

Example:

Request example

{
  "category": {
    "coding": [
      {
        "system": "eHealth/composition_categories",
        "code": "LIVE_BIRTH"
      }
    ]
  },
  "type": {
    "coding": [
      {
        "system": "eHealth/composition_types",
        "code": "NEWBORN"
      }
    ]
  },
  "event": [
    {
      "code": {
        "coding": [
          {
            "system": "eHealth/composition_events",
            "code": "COMPOSITION_VALIDITY_PERIOD"
          }
        ]
      },
      "period": {
        "start": "2020-06-26T15:22:53.403Z",
        "end": "2020-07-26T15:22:53.403Z"
      }
    }
  ],
  "subject": {
    "type": {
      "coding": [
        {
          "system": "eHealth/composition",
          "code": "string"
        }
      ],
      "text": "string"
    },
    "value": "e49abc30-6d17-11ea-b83c-673680173afa"
  },
  "encounter": {
    "type": {
      "coding": [
        {
          "system": "eHealth/composition",
          "code": "string"
        }
      ],
      "text": "string"
    },
    "value": "e49abc30-6d17-11ea-b83c-673680173afa"
  },
  "author": {
    "type": {
      "coding": [
        {
          "system": "eHealth/composition",
          "code": "string"
        }
      ],
      "text": "string"
    },
    "value": "e49abc30-6d17-11ea-b83c-673680173afa"
  },
  "section": {
    "focus": {
      "type": {
        "coding": [
          {
            "system": "eHealth/composition",
            "code": "string"
          }
        ],
        "text": "string"
      },
      "value": "e49abc30-6d17-11ea-b83c-673680173afa"
    }
  },
  "extension": [
    {
      "valueCode": "AUTHORIZE_WITH",
      "valueUuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    {
      "valueCode": "IS_ACCIDENT",
      "valueBoolean": true
    },
    {
      "valueCode": "TREATMENT_VIOLATION",
      "valueString": "late_arrival"
    },
    {
      "valueCode": "TREATMENT_VIOLATION_DATE",
      "valueDate": "2020-12-12"
    },
    {
      "valueCode": "IS_INTOXICATED",
      "valueBoolean": true
    },
    {
      "valueCode": "IS_FOREIGN_TREATMENT",
      "valueBoolean": true
    },
    {
      "valueCode": "IS_FORCE_RENEW",
      "valueBoolean": true
    }
  ]
}

Authorize*

Вимоги до авторизації: яким чином надається доступ до використання методу

Request to process the request using a token in the headers

Headers*

Наприклад:

Content-Type:application/json
Authorization:Bearer c2778f3064753ea70de870a53795f5c9
api-key:uXhEczJ56adsfh3Ri9SUkc4en

Validate request*

Наприклад:

Validate request using JSON schema
1. In case validation failed - generate 422 error

JSON schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "verification_code": {
      "type": "string"
    }
  },
  "required": [
    "verification_code"
  ],
  "additionalProperties": false
}

Request data validation*

Валідація даних

Parameters that are used when processing the request

Configuration parameters

Наприклад: Доступ до методу визначається скоупом covid_certificate:get . Дозвіл на даний скоуп визначається адміністратором Системи шляхом конфігурування скоупів в контексті клієнтів і ролей.

Dictionaries

Потрібно вказати довідники, які використовує метод API

Processing*

Потрібно описати процеси, які відбуваються з даними

1. Using global parameters

Потрібно викликати глобальні параметри (Global parameters), щоб отримати наведені нижче параметри

Response structure*

See on Apiary

Example:

Response example

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "PENDING",
    "eta": "string",
    "doneAt": "string",
    "links": [
      {
        "entity": "eHealth/composition",
        "href": "composition/0daaad78-6cfb-11ea-9cd6-afab698838bc",
        "error": "string"
      }
    ]
  }
}

Post-processing processes*

Що має відбутися в ЦБД після опрацювання та відправлення відповіді, тощо

HTTP status codes*

HTTP status code	Message	What caused the error

Backward compatibility

Сумісність з попередніми версіями методу

Get Forbidden group list_NEW

Required parameters are marked with "*"

Purpose*

Specification*

Logic*

Preconditions

Global and configurable parameters

Input parameters

Filters

Request structure*

Authorize*

Headers*

Validate request*

Request data validation*

Parameters that are used when processing the request

Configuration parameters

Dictionaries

Processing*

1. Using global parameters

Response structure*

Post-processing processes*

HTTP status codes*

Backward compatibility