Request Formats for HTTP Methods

HTTP GET: Getting a list of elements of type Entity

1. HTTP request template: /api/v1/{domain}/{entity}.{format}?query

Element Description
entity Resource name (entity type)
format The format in which the answer will be presented. The options are:
  • Json
  • Xml
query Subquery to the list of Elements. Everything after the “?” (question mark) counts as a request
Element Type Description
filter string Filtering parameters, for example filter = {abn_LastName: '%NATEC%'}
page int Pagination page number
pagesize string Pagination page size

2. Request headers

Header Valid value
Authorization Basic Autorization
global_unique_id Unique request ID.
system External system code for identification, for example = ‘300’
Content-type application/json
Accept application/json
If-Modified-Since HTTP Date, by example Tue, 22 Sep 2020 09:21:24 GMT

3. response headers

Header Valid value
Last-Modified HTTP Date, by example Tue, 22 Sep 2020 09:21:24 GMT

HTTP GET: Getting a specific Element of the Entity Type

1. HTTP request template: /api/v1/{domain}/{entity}/{Id}.{format}

Element Description
entity Resource name (entity type)
format The format in which the answer will be presented. The options are:
  • Json
  • Xml
query Subquery to the list of Elements. Everything after the “?” (question mark) counts as a request
Element Type Description
filter string Filtering parameters, for example filter = {abn_LastName: '%NATEC%'}
page int Pagination page number
pagesize string Pagination page size

2. Request headers

Header Valid value
Authorization Basic Autorization
global_unique_id Unique request ID.
system External system code for identification, for example = ‘300’
Content-type Application/json
Accept application/json
If-Modified-Since HTTP Date, by example Tue, 22 Sep 2020 09:21:24 GMT

3. response headers

Header Valid value
Last-Modified HTTP Date, by example Tue, 22 Sep 2020 09:21:24 GMT

HTTP PUT: Editing an Entity Type Element

1. HTTP request template: /api/v1/{domain}/{entity}/{Id}.{format}?query

Element Description
entity Resource name (entity type)
id Identifier for editing a record
format Optional parameter. The format in which the response will be presented is json by default. The options are:
  • Json
  • Xml
query Subquery to the list of Elements. Everything after the “?” (question mark) counts as a request
Element Type Description
lang string Specifying the language of the content of the request body in ISO 639-1 format

2. Request headers

Header Valid value
global_unique_id Unique request ID.
Authorization Basic Autorization
Content-type Application/json
system External system code for identification, for example = ‘300’
Accept application/json

3. request body

Field name Type Description
AttributesNames:
AttributesValue		 Пара
Key:Value		 An array of entity attributes
Entities

HTTP POST: Creating a new Element of Entity Types

1. HTTP request template: /api/v1/{domain}/{Entity}.{format}?query

Element Description
entity Resource name (entity type)
format Optional parameter. The format in which the response will be presented is json by default. The options are:
  • Json
  • Xml
query Optional parameter. Subquery to the list of Elements. Everything after the “?” (question mark) counts as a request
Element Type Description
lang string Specifying the language of the content of the request body in ISO 639-1 format

2. Request headers

Header Valid value
global_unique_id Unique request ID.
Authorization Basic Autorization
Content-type Application/json
system External system code for identification, for example = ‘300’
Accept application/json

3. request body

Field name Type Description
AttributesNames:
AttributesValue		 Пара
Key:Value		 An array of entity attributes
Entities

HTTP POST: Doing an Action for Element of Entity Types

1. HTTP request template: /api/v1/{domain}/{Entity}/action/{Action}.{format}?query

Element Description
entity Resource name (entity type)
Action Action name (operation for an entity)
format Optional parameter. The format in which the response will be presented is json by default. The options are:
  • Json
  • Xml
query Optional parameter. Subquery to the list of Elements. Everything after the “?” (question mark) counts as a request
Element Type Description
lang string Specifying the language of the content of the request body in ISO 639-1 format

2. Request headers

Header Valid value
global_unique_id Unique request ID.
Authorization Basic Autorization
Authorization Application/json
system External system code for identification, for example = ‘300’
Accept application/json

3. request body

Field name Type Description
AttributesNames:
AttributesValue		 Пара
Key:Value		 An array of entity attributes
Entities

HTTP POST: Creating an new element Sub-Entity of Types

1. HTTP request template: /api/v1/{domain}/{entity}/{ParentId}/{sub-entity}.{format}?query

Element Description
entity Resource name (entity type)
sub-entity Имя ресурса (Type of Sub-entity)
ParentId Parent entity id
format Optional parameter. The format in which the response will be presented is json by default. The options are:
  • Json
  • Xml
query Optional parameter. Subquery to the list of Elements. Everything after the “?” (question mark) counts as a request
Element Type Description
lang string Specifying the language of the content of the request body in ISO 639-1 format

2 Request headers

Header Valid value
global_unique_id Unique request ID.
Authorization Basic Autorization
system External system code for identification, for example = ‘300’
Content-type Application/json
Accept application/json

3. request body

Field name Type Description
AttributesNames:
AttributesValue		 Пара
Key:Value		 An array of entity attributes Entities

HTTP DELETE: Deleting the element of Entity Types

5.2 HTTP request template: /api/v1/{domain}/{entity}/{Id}.{format}?query

Element Description
entity Resource name (entity type)
id Resource identifier (entity)
format Optional parameter. The format in which the response will be presented is json by default. The options are:
  • Json
  • Xml
query Optional parameter. Subquery to the list of Elements. Everything after the “?” (question mark) counts as a request
Element Type Description
lang string Specifying the language of the content of the request body in ISO 639-1 format

5.3 Request headers

Header Valid value
Authorization Basic Autorization
global_unique_id Unique request ID.
Content-type Application/json
system External system code for identification, for example value =‘300’
Accept application/json

HTTP PATCH (reserved): Partially editing the element of Entity Types

1. HTTP request template: /api/v1/{domain}/{entity}/{Id}.{format}?query

Element Description
entity Resource name (entity type)
format The format in which the answer will be presented. The options are:
  • Json
  • Xml
query Subquery to the list of Elements. Everything after the “?” (question mark) counts as a request
Element Type Description
page int Pagination page number
pagesize string Pagination page size

2. Request headers

Header Valid value
global_unique_id Unique request ID.
Authorization Basic Autorization
Content-type Application/json
system External system code for identification, for example = ‘300’
Accept application/json

3. request body

Название Type Description
AttributesNames:
AttributesValue		 Пара
Key:Value		 An array of entity attributes Entities

Handling Errors When Calling HTTP Methods

At the general level of HTTP interaction, the following logic for handling errors through HTTP status codes is assumed:

2xx (Success) - success, there is no point to retry the request, the status codes can be detailed:

  • 200 OK (Success) - if PUT completed without errors
  • 201 Created - if POST is successful, record has been added

4xx (Client error responses) - an error in the formation of a request, there is no point in repeating, except for individual codes 408 (immediate retry) and 409 (delayed retry), for other error codes it is necessary to change the request format before retrying or resolve the issue with authorization, status codes can be detailed:

  • 404 (Not Found) - if request URL is invalid
  • 400 (Bad Request) - if an invalid API entity is specified
  • 401 (Unauthorized) - if the specified username / password pair is incorrect
  • 403 (Forbidden) - if there is no access to entities
  • 408 (Request Timeout) - you want to retry the request immediately
  • 409 (Conflict) - indicates that the request cannot be processed due to a conflict, for example, a parallel request conflict - usually due to an incorrect (too short) timeout for waiting for a response or command execution. You need to repeat the request after a while!

5xx (Server error responses) - a logical error on the server side, there is no point in repeating, except for a separate code 503 (Service unavailable) - this error requires a delayed repetition after the time specified in the request response. The status codes are detailed below:

  • 500 (Internal Server Error) - business logic error, detailed Description is given in the Message and Data tags
  • 501 (Not implemented) - if you try to call DELETE
  • 503 (Service unavailable) - if there is no API access to the linked databases or the authorization parameters of the server itself are outdated (not related to API authorization - the technical account is locked, etc.)

IMPORTANT! Incorrect configuration of timeouts for the API during integration between systems can lead to a looping of errors 408 and 409 - in this case, it is necessary to reconcile the timeout values of the request initiator and the request executor, namely, the waiting timeout on the initiator's side must always be strictly greater, than the timeout for executing the request on the executor side.

Below is the Description of the entity level error message response structure (usually for codes 5xx and 4xx, except for authorization errors and IIS server errors):

Field name Mandatory Description
LevelMessage yes Object
ErrNumber yes Object
Message yes Error Description
State yes Error State
HelpLink no Link to documentation expanding information regarding the error
Xml no ErrNumber of the error-reason contained in Data
Data Object The error-reason for the current error (in other words nested error) in the same structure, for the example below in XML format:
ResolveUrl A link to a web application that allows you to correct data that affects the fact of an error

It is important to understand that the Data tag contains errors of a similar structure - thus errors can be nested - i.e. when one error becomes a reason for another, higher-level one, then both errors come in the response, while the first error is contained in the "Data" tag. For ease of handling errors, the very first ErrNumber from the first cause error is listed in the Xml tag. An example of an error response with nested error-causes is given below Error Responses

HTTP Call Examples

Request format

An example GET request to get Customers records with the name NATEC:

GET http://servername:port/api/v1/Bss/customers.json?lang=uk&pageIndex=0&pageSize=1000&filter=%7babn_LastName%7Babn_LastName%3A%27%25NATEC%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

An example of a GET request to get one Customers record by ID with the If-Modified-Since transfer:
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

An example of a POST request to create a Person client type

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":"Klinton Bill",
"Customer_FirstName":"Bill",
"Customer_MiddleName":"",
"Customer_SearchName":"Klinton",
"CustomerLanguageId":1,
"StatusId":2,
"CustomerDate":"2019-05-08T11:55:39.9285053+03:00",
"GroupID":1,
"LocationID":1
}

An example of a POST request to create a client for a Legal entity under the Association level

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":"NATEC LLC",
"Customer_SearchName":"NATEC LLC"",
"CustomerLanguageId":1,
"StatusId":2,
"CustomerDate":"2019-05-08T11:55:39+03:00",
"GroupID":1,
"LocationID":1
}

An example of a PUT request to edit a client's full name with 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":"Trump Donald",
"Customer_FirstName":"Donald",
"Customer_MiddleName":"",
"Customer_SearchName":"Trump",
"CustomerLanguageId":1,
"StatusId":2,
"CustomerDate":"2019-05-08T11:55:39+03:00",
"GroupID":1,
"LocationID":1
}

Response format

An example GET response to retrieve Customers records by 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":"NATEC LLC.",
"abn_Login":"",
"abn_MiddleName":"",
"abn_ModifiedBy":"username",
"abn_ModifiedDate":"2019-10-31T17:58:35.75",
"abn_ModifiedFrom":"hostname",
"abn_NestedSets_Left":398155,
"abn_NestedSets_Right":398156,
"abn_Password":"09B0B566-2570-4447-BDF5-5304813834B8",
"abn_PositionCode":"",
"abn_ShowPhoneDirectory":0,
"abn_WorkPlace":"01234567890",
"abonentFullName":"NATEC LLC.",
"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":"NATEC LLC. {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":"Brach 0001",
"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

An example of wrong authorization

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" }

An example of getting response from cache

{
"headerId": "1892ae73-f1db-47e0-9084-35e8aef993f3",
"idempotent": {
"status": "IsCompleted",
"dateModify": "2019-06-09T15:53:18.5599139Z",
"data": {
"id": 100000257,
"lang": "uk ",
"idType": 1
} }

Database level error example

{
"LevelMessage":"17",
"ErrNumber":"50240",
"Message": "Error by activating the tariff plan template (RepresentationTariffPlanBind)",
"State": "1",
"HelpLink": "",
"Xml": "50248",
"Data": {
"LevelMessage": "17",
"ErrNumber": "50271",
"Message": "Error creating service subscription:",
"State": "1",
"HelpLink": "",
"Xml": "50248",
"Data": {
"LevelMessage": "17",
"ErrNumber": "50248",
"Message": "Error changing service status: invalid srs_id = 12345",
"State":"1",
"HelpLink":"",
"Xml":"50248",
"Data": null,
"ResolveUrl":""
},
"ResolveUrl":""
},
"ResolveUrl":""
}

The list of errors related to CRUD operations of each REST entity is given in the REST API Specs in the Errors Mapping section