Формати запитів для HTTP-методів

HTTP метод GET: Доступ до списку елементів типу Entity

1. Шаблон HTTP запиту: /api/v1/{domain}/{entity}.{format}?query

Елемент

Опис

entity

Ім'я ресурсу (тип сутності)

format

Формат, в якому буде представлений відповідь. варіанти:

Json
Xml

query

Підзапит до списку елементів. Все що слід після знаку "?" (Знак питання) вважається запитом

Елемент	Тип	Опис
filter	string	Параметри фільтрації, наприклад filter={abn_LastName:'%НАТЕК%'}
page	int	Номер сторінки при паджінаціі
pagesize	string	Розмір сторінки для паджінаціі

2. Заголовки запиту

Заголовок	Допустиме значення
Authorization	Basic Autorization
global_unique_id	Унікальний ідентифікатор запиту.
system	Код зовнішньої системи для ідентифікації, наприклад = ‘300’
Content-type	application/json
Accept	application/json
If-Modified-Since	HTTP Date, наприклад Tue, 22 Sep 2020 09:21:24 GMT

3. заголовки відповіді

Заголовок	Допустиме значення
Last-Modified	HTTP Date, наприклад Tue, 22 Sep 2020 09:21:24 GMT

HTTP метод GET: Доступ до певного Елементу типу Entity

1. Шаблон HTTP запиту: /api/v1/{domain}/{entity}/{Id}.{format}

Елемент

Опис

entity

Ім'я ресурсу (тип сутності)

format

Формат, в якому буде представлений відповідь. варіанти:

Json
Xml

query

Підзапит до списку елементів. Все що слід після знаку "?" (Знак питання) вважається запитом

Елемент	Тип	Опис
filter	string	Параметри фільтрації, наприклад filter={abn_LastName:'%НАТЕК%'}
page	int	Номер сторінки при паджінаціі
pagesize	string	Розмір сторінки для паджінаціі

2. Заголовки запиту

Заголовок	Допустиме значення
Authorization	Basic Autorization
global_unique_id	Унікальний ідентифікатор запиту.
system	Код зовнішньої системи для ідентифікації, наприклад = ‘300’
Content-type	Application/json
Accept	application/json
If-Modified-Since	HTTP Date, наприклад Tue, 22 Sep 2020 09:21:24 GMT

3. заголовки відповіді

Заголовок	Допустиме значення
Last-Modified	HTTP Date, наприклад Tue, 22 Sep 2020 09:21:24 GMT

HTTP метод PUT: Редагування елемента типу Entity

1. Шаблон HTTP запиту: /api/v1/{domain}/{entity}/{Id}.{format}?query

Елемент

Опис

entity

Ім'я ресурсу (тип сутності)

Ідентифікатор для редагування запису

format

Необов'язковий параметр. Формат, в якому буде представлений відповідь, за замовчуванням json. варіанти:

Json
Xml

query

Підзапит до списку елементів. Все що слід після знаку "?" (Знак питання) вважається запитом

Елемент	Тип	Опис
lang	string	Вказівка мови вмісту тіла запиту в форматі ISO 639-1

2. Заголовки запиту

Заголовок	Допустиме значення
global_unique_id	Унікальний ідентифікатор запиту.
Authorization	Basic Autorization
Content-type	Application/json
system	Код зовнішньої системи для ідентифікації, наприклад = ‘300’
Accept	application/json

3. тіло запиту

Назва поля	Тип	Опис
AttributesNames: AttributesValue	Пара Ключ: Значення	Масив атрибутів сутності Entities

HTTP метод POST: Створення нового елемента типу Entity

1. Шаблон HTTP запиту: /api/v1/{domain}/{Entity}.{format}?query

Елемент

Опис

entity

Ім'я ресурсу (тип сутності)

format

Необов'язковий параметр. Формат, в якому буде представлений відповідь, за замовчуванням json. варіанти:

Json
Xml

query

Необов'язковий параметр. Підзапит до списку елементів. Все що слід після знаку "?" (Знак питання) вважається запитом

Елемент	Тип	Опис
lang	string	Вказівка мови вмісту тіла запиту в форматі ISO 639-1

2. Заголовки запиту

Заголовок	Допустиме значення
global_unique_id	Унікальний ідентифікатор запиту.
Authorization	Basic Autorization
Content-type	Application/json
system	Код зовнішньої системи для ідентифікації, наприклад = ‘300’
Accept	application/json

3. тіло запиту

Назва поля	Тип	Опис
AttributesNames: AttributesValue	Пара Ключ: Значення	Масив атрибутів сутності Entities

HTTP метод POST: Виконання дії для елемента типу Entity

1. Шаблон HTTP запиту: /api/v1/{domain}/{Entity}/action/{Action}.{format}?query

Елемент

Опис

entity

Ім'я ресурсу (тип сутності)

Action

Назва действия (операции над сущностью)

format

Необов'язковий параметр. Формат, в якому буде представлений відповідь, за замовчуванням json. варіанти:

Json
Xml

query

Елемент	Тип	Опис
lang	string	Вказівка мови вмісту тіла запиту в форматі ISO 639-1

2. Заголовки запиту

Заголовок	Допустиме значення
global_unique_id	Унікальний ідентифікатор запиту.
Authorization	Basic Autorization
Authorization	Application/json
system	Код зовнішньої системи для ідентифікації, наприклад = ‘300’
Accept	application/json

3. тіло запиту

Назва поля	Тип	Опис
AttributesNames: AttributesValue	Пара Ключ: Значення	Массив атрибутов сущности Entities

HTTP метод POST: Створення нового елемента типу Sub-Entity

1. Шаблон HTTP запиту: /api/v1/{domain}/{entity}/{ParentId}/{sub-entity}.{format}?query

Елемент

Опис

entity

Ім'я ресурсу (тип сутності)

sub-entity

Ім'я ресурсу (тип підпорядкованої сутності)

ParentId

Ідентифікатор вищестоящої сутності

format

Необов'язковий параметр. Формат, в якому буде представлений відповідь, за замовчуванням json. варіанти:

Json
Xml

query

Елемент	Тип	Опис
lang	string	Вказівка мови вмісту тіла запиту в форматі ISO 639-1

2 Заголовки запиту

Заголовок	Допустиме значення
global_unique_id	Унікальний ідентифікатор запиту.
Authorization	Basic Autorization
system	Код зовнішньої системи для ідентифікації, наприклад = ‘300’
Content-type	Application/json
Accept	application/json

3. тіло запиту

Назва поля	Тип	Опис
AttributesNames: AttributesValue	Пара Ключ: Значення	Масив атрибутів сутності Entities

HTTP метод DELETE: Видалення елемента типу Entity

5.2 Шаблон HTTP запиту: /api/v1/{domain}/{entity}/{Id}.{format}?query

Елемент

Опис

entity

Ім'я ресурсу (тип сутності)

Ідентифікатор ресурсу (сутності)

format

Необов'язковий параметр. Формат, в якому буде представлений відповідь, за замовчуванням json. варіанти:

Json
Xml

query

Елемент	Тип	Опис
lang	string	Вказівка мови вмісту тіла запиту в форматі ISO 639-1

5.3 Заголовки запиту

Заголовок	Допустиме значення
Authorization	Basic Autorization
global_unique_id	Унікальний ідентифікатор запиту.
Content-type	Application/json
system	Код зовнішньої системи для ідентифікації, наприклад значение = ‘300’
Accept	application/json

HTTP метод PATCH (зарезервировано): Часткове Редагування елемента типу Entity

1. Шаблон HTTP запиту: /api/v1/{domain}/{entity}/{Id}.{format}?query

Елемент

Опис

entity

Ім'я ресурсу (тип сутності)

format

Формат, в якому буде представлений відповідь. варіанти:

Json
Xml

query

Підзапит до списку елементів. Все що слід після знаку "?" (Знак питання) вважається запитом

Елемент	Тип	Опис
page	int	Номер сторінки при паджінаціі
pagesize	string	Розмір сторінки для паджінаціі

2. Заголовки запиту

Заголовок	Допустиме значення
global_unique_id	Унікальний ідентифікатор запиту.
Authorization	Basic Autorization
Content-type	Application/json
system	Код зовнішньої системи для ідентифікації, наприклад = ‘300’
Accept	application/json

3. тіло запиту

Назва	Тип	Опис
AttributesNames: AttributesValue	Пара Ключ: Значення	Масив атрибутів сутності Entities

Обробка помилок при виклику HTTP методів

На загальному рівні HTTP взаємодії передбачається наступна логіка обробки помилок через статус коди HTTP:

2xx (Success) - успіх, повторювати запит сенсу немає, статус коди можуть бути деталізовані:

200 OK (успіх) – якщо PUT виконаний без помилок
201 Created (Запис доданий) – якщо POST виконаний без помилок

4хх (Client error responses) - помилка формування запиту, повторювати сенсу немає, крім окремих кодів 408 (негайний повтор) та 409 (відкладений повтор), для інших кодів помилок потрібно змінити формат запиту перед повторним виконанням або вирішити питання з авторизацією, статус коди можуть бути деталізовані:

404 Not Found (Дані не знайдено) - якщо невірний URL запиту
400 Bad Request (Невірний запит) - якщо вказана невірна сутність API
401 Unauthorized (Неавторизований доступ) - якщо зазначена пара логін / пароль невірні
403 Forbidden (Доступ заборонений) - якщо немає доступу до сутностей
408 (Request Timeout) - потрібно повторити запит негайно
409 (Conflict) - вказує, что запит не може буть оброблений через конфлікт, например, конфлікт Паралельно запиту - зазвичай є наслідком неправильного (занадто короткого) таймаута на очікування відповіді або виконання команди. Потрібно повторити запит через деякий час!

5хх (Server error responses) - логічна помилка на стороні сервера, повторювати сенсу немає, крім окремого коду 503 (Service unavailable) - дана помилка вимагає відкладеного повторення поза часом, визначеним у відповіді запиту. Статус коди деталізовані нижче:

500 Internal Server Error (Внутрішня помилка сервера) - помилка бізнес-логіки, детальне Опис приведено в тегах Message і Data
501 Not implemented (Не виконано) - якщо спробувати викликати DELETE
503 Service unavailable - якщо не маєте доступу API до пов'язаним БД або параметри авторизації самого сервера застаріли (не пов'язані з авторизацією API - технічна обліковий запис заблоковано і т.д.)

ВАЖЛИВО! Невірна конфігурації таймаутів для АПИ при інтеграції між системами може привести до зациклення помилок 408 і 409 - в цьому випадку потрібно виконати узгодження значень таймаутів боку-ініціатора запиту і сторони-виконавця запитів, а саме - затримку читання на стороні ініціатора завжди повинен бути строго більше, ніж таймаут на виконання запиту на стороні-виконавця.

Нижче наведено Опис структури відповіді повідомлення про помилку рівня сутностей (зазвичай для кодів 5хх і 4хх, крім помилок авторизації і помилок сервера IIS):

Назва поля	Обов'язковість	Опис
LevelMessage	так	об'єкт
ErrNumber	так	об'єкт
Message	так	Детальний Опис помилки
State	так	Error State
HelpLink	ні	Посилання на документацію, яка розширює інформацію щодо помилки
Xml	ні	Номер ErrNumber найпершої помилки-причини, що міститься в Data
Data	об'єкт	помилка-причина для поточної помилки (іншими словами вкладена помилка) в тій же структурі, для прикладу нижче в форматі XML:
ResolveUrl		Посилання на веб-додаток, що дозволяє виправити дані, що впливають на факт появи помилки

Важливо розуміти, що тег Data містить помилки аналогічної структури - тим самим помилки можуть бути вкладеними - тобто коли одна помилка стає причиною для іншого, більш верхнеуровневой, то тоді обидві помилки приходять у відповіді, при це перша помилка міститься в тезі «Data». Для зручності обробки помилок, найперше значення ErrNumber з першої помилки-причини приведено в тезі Xml. Приклад помилкового відповіді з вкладеними помилками-причинами наведено нижче Error Responses

Приклади викликів HTTP

Request format

Приклад запиту GET для отримання записів Customers з ім'ям НАТЕК:

GET http://servername:port/api/v1/Bss/customers.json?lang=uk&pageIndex=0&pageSize=1000&filter=%7babn_LastName%3a%27%25%D0%9D%D0%90%D0%A2%D0%95%D0%9A%25%27%7d HTTP/1.1

accept: application/json
system: 300
global_unique_id: 6d07332c-2e63-4d49-91d2-ee01e600f7ff
Authorization: Basic YXBpX3VzZXI6V2lkZWNvdXAx
Content-Type: application/json
Host: servername:port
Content-Length: 0

Приклад запиту GET для отримання запису Customers по ID з передачею If-Modified-Since:
GET http://servername:port/api/v1/Bss/customers/1041838.json HTTP/1.1

accept: application/json
if-modified-since: Tue, 22 Sep 2020 09:21:24 GMT
system: 300
global_unique_id: 6d07332c-2e63-4d49-91d2-ee01e600f7ff
Authorization: Basic YXBpX3VzZXI6V2lkZWNvdXAx
Content-Type: application/json
Host: servername:port
Content-Length: 0

Приклад запиту POST для створення клієнта Фізичної особи

POST http://servername:port/api/v1/Bss/customers HTTP/1.1

Authorization: Basic ZGVtbzpkZW1v
Content-Type: application/json
global_unique_id: 6b80d0f6-62df-4507-b115-e5245c0b340c
Connection: Keep-Alive

{ "IDType":1, "ProfileType":1 "ParentID":1, "Name":"Порошенко Петро", "Customer_FirstName":"Петро", "Customer_MiddleName":"Порошенко", "Customer_SearchName":"Порошенко П.О.", "CustomerLanguageId":1, "StatusId":2, "CustomerDate":"2019-05-08T11:55:39.9285053+03:00", "GroupID":1, "LocationID":1 }

Приклад запиту POST для створення клієнта Юридичної особи з Асоціації

POST http://servername:port/api/v1/Bss/associations/1042338/customers HTTP/1.1

Authorization: Basic ZGVtbzpkZW1v
Content-Type: application/json
global_unique_id: 6b80d0f6-62df-4507-b115-e5245c0b350c
Connection: Keep-Alive

{ "IDType":1, "ProfileType":2, "Name":"Товариство з обмеженою відповідальністю Первомайський Гірничо-збагачувальний комбінат", "Customer_SearchName":"Первомайський ГЗК ТОВ", "CustomerLanguageId":1, "StatusId":2, "CustomerDate":"2019-05-08T11:55:39+03:00", "GroupID":1, "LocationID":1 }

Приклад запиту PUT для редагування ПІБ клієнта с ID=1041838

PUT http://servername:port/api/v1/Bss/customers?id=1041838 HTTP/1.1

Authorization: Basic ZGVtbzpkZW1v
Content-Type: application/json
global_unique_id: ac6495d1-5118-494a-a737-844f6c76ba46
Host: servername:port

{ "IDType":1, "ProfileType":1 "ParentID":1, "Name":"Зеленський", "Customer_FirstName":"Володимир", "Customer_MiddleName":"Олександрович", "Customer_SearchName":"Зеленський В.О.", "CustomerLanguageId":1, "StatusId":2, "CustomerDate":"2019-05-08T11:55:39+03:00", "GroupID":1, "LocationID":1 }

Response format

Приклад відповіді GET для отримання записів Customers по ID:

HTTP/1.1 200 OK
Content-Length: 78597
Content-Type: aplication/json
Last-Modified: Tue, 22 Sep 2020 09:21:24 GMT
Server: Microsoft-IIS/10.0
cache-scenario: scenario.1
X-Powered-By: ASP.NET
Date: Sun, 27 Sep 2020 11:18:51 GMT


                {

                "data":[

                {

                "abn_Balance":0.000000,

                "abn_CreateDate":"2019-10-31T17:58:35.697",

                "abn_Date":"2019-11-01T00:00:00",

                "abn_Employe_Export_ID":"",

                "abn_Employee_ID":"",

                "abn_ExternalID":8836891,

                "abn_FirstName":"",

                "abn_Guid":"b75d56c7-1b84-4571-8e6c-09a3aeffc0a1",

                "abn_HasNotEmptyPrepaid":0,

                "abn_ID":165,

                "abn_ID_Boss":164,

                "abn_IsExistAD":0,

                "abn_IsGuest":0,

                "abn_LastName":"ТОВАРИСТВО З ОБМЕЖЕНОЮ ВІДПОВІДАЛЬНІСТЮ \"НАТЕК СЕРВІС\"",

                "abn_Login":"",

                "abn_MiddleName":"",

                "abn_ModifiedBy":"IVR_V.BORSHCHEVSKA_35683",

                "abn_ModifiedDate":"2019-10-31T17:58:35.75",

                "abn_ModifiedFrom":"BIS",

                "abn_NestedSets_Left":398155,

                "abn_NestedSets_Right":398156,

                "abn_Password":"09B0B566-2570-4447-BDF5-5304813834B8",

                "abn_PositionCode":"",

                "abn_ShowPhoneDirectory":0,

                "abn_WorkPlace":"01234567890",

                "abonentFullName":"ТОВАРИСТВО З ОБМЕЖЕНОЮ ВІДПОВІДАЛЬНІСТЮ \"НАТЕК СЕРВІС\"",

                "acnt_ID":86,

                "acnt_ID_count":1,

                "acnt_IsPersonal":0,

                "acnt_Number":"8132725",

                "acnt_Number_Personal":"",

                "actp_ID":21,

                "actpd_Name":"ГКО",

                "actpd_Name_Personal":"",

                "aut_ID_count":0,

                "aut_NameAuthCode":"",

                "aut_NumberAts":0,

                "bossFullName":"ТОВАРИСТВО З ОБМЕЖЕНОЮ ВІДПОВІДАЛЬНІСТЮ \"НАТЕК СЕРВІС {01234567890}",

                "cntr_ID_count":0,

                "cntr_Name":"",

                "com_Id":1,

                "dep_ID":202,

                "ext_ExtNum":"",

                "ext_ID_count":0,

                "grp_ID":100,

                "grp_Name":"ByDefault",

                "isEditAllow":1,

                "isEditWorkPlace":0,

                "lng_ID":1,

                "loc_Name":"ГО КС(КС)",

                "location_ID":7,

                "ntw_ID":1000,

                "pbx_networkName":"United",

                "profileType":2,

                "rptURL":"",

                "subsCount":0,

                "tnst_ExternalID":2,

                "tnst_ID":10,

                "tnt_AccountMandatory":1,

                "tnt_ID":130,

                "total":52,

                "treeNodeType":"Customer",

                "trf_ID":2

                }

                ]

                }

Error Responses

Приклад помилкової авторизації

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json; charset=utf-8
WWW-Authenticate: Negotiate
WWW-Authenticate: NTLM
Proxy-Support: Session-Based-Authentication


                {
                "type":"https://tools.ietf.org/html/rfc7235#section-3.1",

                "title":"Unauthorized",

                "status":401,

                "traceId":"0HLM1RANTI6TH:00000001"
                }

Приклад спрацювання перевірки на ідемпотентність


                {

                "headerId": "1892ae73-f1db-47e0-9084-35e8aef993f3",

                "idempotent": {

                "status": "IsCompleted",

                "dateModify": "2019-06-09T15:53:18.5599139Z",

                "data": {

                "id": 100000257,

                "lang": "uk ",

                "idType": 1

                }  }

Приклад помилки рівня БД


                {

                "LevelMessage":"17",

                "ErrNumber":"50240",

                "Message":"Помилка установки підключеного шаблона тарифного плану (RepresentationTariffPlanBind)",

                "State":"1",

                "HelpLink":"",

                "Xml":"50248",

                "Data":{

                "LevelMessage":"17",

                "ErrNumber":"50271",

                "Message":"Помилка створення підписки на сервіс: ",

                "State":"1",

                "HelpLink":"",

                "Xml":"50248",

                "Data":{

                "LevelMessage":"17",

                "ErrNumber":"50248",

                "Message":"Помилка зміни статусу послуги: невірний srs_id=12345",

                "State":"1",

                "HelpLink":"",

                "Xml":"50248",

                "Data": null,

                "ResolveUrl":""

                },

                "ResolveUrl":""

                },

                "ResolveUrl":""

                }

Перелік помилок, пов'язаних з CRUD операціями кожної REST суті наведено в специфікації REST API Specs в розділі Errors Mapping