REST API

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 or PATCH method), the proposed API is idempotent for all methods, including POST and DELETE.

HTTP method	Safe	Idempotent	Cached
GET	Yes	Yes	Yes
POST	No	Yes	Yes
PUT	No	Yes	Yes
PATCH	No	Yes	Yes
DELETE	No	Yes	Yes

An real Implementation of methods depends on some developer as well ;-)

The REST API engine is provided by the MEF.DEV platform, expands the package functionality available on it, by exposing its resources (for example, accounts, subscribers, or customers from Telecom BSS). This exposure is based on unique URI values with Entities and Actions Names within the Alias (kind of domain). It is important to understand that the transparency of the design 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. Operations (actions) can be applied to different entities - this is also determined by the developers of a specific plugin that implements specific entities.

A Nuget package example with these capabilities is available as BSS.Entities

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

Standard Package requests

Sending the standard requests to the package will be demonstrated by the GET requests example

Design-wise, you can develop and add any parameters, headers, and fields within the request, but you should handle them with the input and output models of the package. To operate with the platform with specific tasks, you should use HTTP context as well as some ServiceProvider, for instance configProvider, or dynamic Pligin Configuration

Specific Action requests

To implement specific logic which should outstanding of standard HTTP methods, you have got to use the Action implementation, by example create-item

Note to mention the MEF.DEV platform automatically expose the unique URI values for specific version of the data models (Entities, Actions and Custom Views). Definition for these models is part of domain-driven-design phase and implements as SID-model for some Alias, but should be supported by developer in form of swagger specification attributes set

To support the pure REST architecture, we highly recommend 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:

Example of SID-model for the Telecom BSS domain is available as BSS.Entities

Idempotency

You can look at scenario below to understand the handling of HTTP requests within the platform

The global_unique_id option is used to support Idempotency and avoid duplication errors. Each successful CRUD operation, including for the POST method, is stored in the platform's distributed cache. In case of receiving a second request, the API returns a previously saved response from the cache. The request is identified as repeated by the value of the 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:

Authorization types

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	Intranet
- Basic Authorization - oAuth 2.0 - JWT tokens	- URL (token) - Basic Authorization - Windows (NTLM/Kerberos) - JWT tokens

To use Basic Authorization authorization, you have got to create the login-password pair under the SETTINGS\CREDENTIALS section of your profile on the platform, accessed by clicking on the user icon in the upper right corner. After clicking on the ADD button you will be able to set up the user login and password with the Basic Auth authorization type.

To use authorization through the URL (token), the URL should contain the value Authorization={credentials}, where {credentials} 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.

Date and time format

To send parameters of date and time, the format ISO 8601 is used, an example of date and time is below:

Time	Value
06/18/2019 0:00:00 Kiev (Europe)	2019-06-18T00:00:00+03:00

guide for сreation of Backend package from template

HTTP platform caching

For server-side caching, the MEF.DEV platform uses a validity model. In the validity model, the server sends the Last-Modified date to the client along with the data, and the client caches the Last-Modified date along with the response. When you make a second request to the same resource, you must send the saved date in the IF-Modified-Since header. The server uses this date to check if the resource you are requesting has changed since the last time it was accessed (remember, the server is the only reliable source). If the resource did change, then it will send the last copy of the data along with the http code 200 OK. Otherwise, it will send the http code 304 Not Modified. The cache validity model requires additional effort from the developer when developing the client side - if you received Last-Modified with a resource, send it in the IF-Modified-Since header field in subsequent requests.