REST API using

General approach

For external interaction with the platform, the RESTful API is used, however, given the support of Legacy systems (the inability to edit records through the PUT method), the proposed API is idempotent for all methods, including POST:

The general list of REST entities and relations between them is determined by the plugin developers and combined into domains (for example, to separate the Customers of the telecom operator and the Customers of the fintech sector) - an example of a domain name is bss in the following url:
http://servername:port/api/v1/Bss/addresses/actions/sync.json?lang=uk

you should pay attention to the formation of url for specifying entity relationships - which actually implements the principle of passing the ParentID parameter when creating a specific REST entity - in the example below, we see the creation of the Subscribers entity in the previously created Customers entity with the identifier 10000001:
POST http://servername:port/api/v1/Bss/customers/1000001/subscribers.json?lang=uk

It is important to understand that the transparency of the architecture for all platform developers is achieved by standardizing the naming of entities - therefore, a mandatory recommendation is to nominate entities with plural nouns, and perform operations for them with verbs. In the example below, the activation of a previously created subscriber with the identifier 2000101 will be performed:
POST http://servername:port/api/v1/Bss/subscribers/2000101/activate.json?lang=uk

Operations (actions) can be applied to different entities - this is also determined by the developers of a specific plugin that implements specific entities. The example below shows the action for changing the status for different entities:
POST http://servername:port/api/v1/Bss/subscribers/2000101/changeStatus.json?lang=uk
POST http://servername:port/api/v1/Bss/customers/1000001/changeStatus.json?lang=uk

If you need to change a previously created REST entity, you should use the PUT method and the unique identifier of the REST entity - below is an example of editing Customers data:
PUT http://servername:port/api/v1/Bss/customers/1000001.json?lang=uk

In fact, to indicate the relationship of entities with each other, the concept of explicitly pointing to a parent entity (Entity) through the ParentID parameter in the Path value of the Entity/{ParentID}/SubEntity format is used, below is an example of relationships between Associations, Customers and Subscribers entities, including their subordinate entities (Sub-Entity) Contracts, Profiles, Addresses and Properties:

Background interaction API

Service Flow

API Layer: implements REST http interface, authorization, caching and call idempotency.
Backend Plugin: implements business logic such as CRUD operations for an entity (such as Customers).

Idempotency: logic for processing the global_unique_id parameter

The global_unique_id parameter is used to avoid duplicate data insertion into the database - each successful CRUD operation, including for the POST method, is saved to the distributed cache of the Web publishing server (implemented at the level of a separate MS SQL Server database - SQL Server distributed cache Microsoft.Extensions.Caching.SqlServer package) and if a second request is received, the API returns the previously saved response from the cache. The request is identified as repeated by the value global_unique_id.

The response body always contains an indication of the check status ("IsCompleted" informs that the idempotency check was triggered and the response body was used from the Web server cache, the value " Added " says about the fact that the check is negative and the result of the execution has been added to the cache, the examples are below - it is important to understand that the data tag will contain the Response-model of the data of a specific Entity:

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

} } }

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

} } }

API Authorization

For authorization on API methods, support for various types of authorization at the level of each controller is implemented in 2 modes of platform deployment - Internet and Intranet, the supported authorization types for each type of deployment are listed below:

Internet:

  • Basic Authorization
  • oAuth 2.0

Intranet:

  • URL (token)
  • Basic Authorization
  • Kerberos
  • NTLM

Thus, for authorization on API methods, it is enough to use Basic Authorization at the level of transferring http request headers. The current values of the login-password pair should be requested from the administrator of your organization.

To use authorization through a token, the URL should contain the value Authorization = , where is the standard form for the Basic Authorization authorization scheme. It is important to understand that since the transfer goes through url, then in the form of Url Encoded, for example:

http://servername:port/api/v1/Bss/versioninfo.json?Authorization=eWl6aGFja0BnbWFpb1234206VGVzdDEyMzQ1Ng%3D%3D

Date and time format for API parameters

To send parameters of date and time, the format ISO 8601 is used, an example of date and time in this format for Kiev (Europe): 06/18/2019 0:00:00 will be 2019-06-18T00:00:00+03:00

API methods

Purpose of HTTP methods

Mapping the operations you need to HTTP methods becomes easier when you know the characteristics of all HTTP methods — since the REST API implementation uses HTTP methods for operations instead of writing different service names for each operation, this section covers the behavior of each HTTP method. Below is a list of methods that are used in REST applications and their properties are shown in relation to each entity:

  • GET: This method is safe and idempotent. Usually used to extract information and has no side effects
  • POST: This method is not secure, but it is idempotent in the implementation of the REST API - this is done to support changeability in Legacy systems, which does not support the PUT method. This method is most commonly used to create Entities
  • PUT: This method is idempotent natively - so it is better to use this method instead of POST to update resources. Avoid using POST to update resources, except for those Entities where changes require historical changes, such as Addresses or Profiles
  • DELETE: as the name suggests, this method is used to delete Entities, but in the REST API implementation it is also idempotent (reserved)