Форматы запросов для 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 Имя ресурса (тип сущности)
id Идентификатор для редактирования записи
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 Имя ресурса (тип сущности)
id Идентификатор ресурса (сущности)
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":"41530968",
"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":"ТОВАРИСТВО З ОБМЕЖЕНОЮ ВІДПОВІДАЛЬНІСТЮ \"НАТЕК СЕРВІС {41530968}",
"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