Форматы запросов для 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":"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