Форматы запросов для HTTP-методов
HTTP метод GET: Доступ к списку элементов типа Entity
1. Шаблон HTTP запроса: /api/v1/{domain}/{entity}.{format}?query
Элемент | Описание | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
entity | Имя ресурса (тип сущности) | ||||||||||||
format | Формат, в котором будет представлен ответ. Варианты:
|
||||||||||||
query |
|
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 |
Формат, в котором будет представлен ответ. Варианты:
|
||||||||||||
query |
Подзапрос к списку элементов. Все что следует после знака “?” (знак вопроса) считается запросом
|
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. Варианты:
|
||||||
query | Подзапрос к списку элементов. Все что следует после знака “?” (знак вопроса) считается запросом
|
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. Варианты:
|
||||||
query |
Необязательный параметр. Подзапрос к списку элементов. Все что следует после знака “?” (знак вопроса) считается запросом
|
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. Варианты:
|
||||||
query |
Необязательный параметр. Подзапрос к списку элементов. Все что следует после знака “?” (знак вопроса) считается запросом
|
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. Варианты:
|
||||||
query |
Необязательный параметр. Подзапрос к списку элементов. Все что следует после знака “?” (знак вопроса) считается запросом
|
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. Варианты:
|
||||||
query |
Необязательный параметр. Подзапрос к списку элементов. Все что следует после знака “?” (знак вопроса) считается запросом
|
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 | Формат, в котором будет представлен ответ. Варианты:
|
|||||||||
query |
Подзапрос к списку элементов. Все что следует после знака “?” (знак вопроса) считается запросом
|
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 с именем НАТЕК:
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