Integration API

Starting with version 2.2 DWKit comes with an Integration API that allows you to request, modify and delete system data through Data Model or Form objects (on the basis of 'Mapping data model').

Prerequisites

You can access Integration API only with an APIKey. APIKey can be specified in the admin panel on the Dashboard page in the Application settings section. APIKey may be represented by any sequence of characters. If the Application settings section does not have APIKey settings, then you need to add them to the database with the following script:

• MSSQL:

  INSERT INTO [dwAppSettings] ([Name], [GroupName], [ParamName], [Value], [Order], [EditorType], [IsHidden])
    VALUES ('IntegrationApiKey', 'Application settings', 'Api key', '', 2, 0, 0)

• PostgreSQL:

  INSERT INTO "dwAppSettings" ("Name", "GroupName", "ParamName", "Value", "Order", "EditorType", "IsHidden")
    VALUES ('IntegrationApiKey', 'Application settings', 'Api key', '', 2, 0, false)

After executing these scripts and refreshing the Dashboard page, the APIKey settings will be available in the Application settings section.

Integration API requests

Application controllers

The Starter Application and all other apps based on DWKit include an IntegrationApiController. Integration API processing is executed with two methods: ModelApi and FormApi. ModelApi performs operations with Data described in the Data Model. FormApi performs operations with data described in the Mapping data model for a Form. Both methods are intended only to set up access and transfer an HTTP request into internal DWKit classes. Their implementation is as follows:

[Route("api/{operation?}/model/{name?}/{level?}/{id?}")]
[HttpGet]
[HttpPost]
public async Task<ActionResult> ModelApi()
{
    try
    {
        var result = await IntegrationApiHttp.Process(HttpContext.Request);
        return Json(result);
    }
    catch (Exception ex)
    {
        return Json(new IntegrationApiFailResponse(ex));
    }
}

[Route("api/{operation?}/form/{name?}/{id?}")]
[HttpGet]
[HttpPost]
public async Task<ActionResult> FormApi()
{
    try
    {
        var result = await IntegrationApiHttp.Process(HttpContext.Request);
        return Json(result);
    }
    catch (Exception ex)
    {
        return Json(new IntegrationApiFailResponse(ex));
    }
}

API for requesting data

Conveying APIKey in requests to Integration API

All requests to Integration API require APIKey. There are three ways of conveying APIKey in requests, and you should use one of them:

• In URL. You can convey APIKey as a parameter with the apikey name in the URL. This parameter is described in the swagger specification and is used in request examples below.
• In HTTP header. You can convey APIKey as an HTTP header parameter with the dwkit-apikey name. This parameter is described in the swagger specification.
• In request's JSON payload. You can convey APIKey as a parameter with the apikey name in request's JSON payload. This parameter is not described in the swagger specification, but will work.

Requesting Form or DataModel by id

The simplest request is an HTTP GET method, requesting data by primary key. To do that you need to form the following URL:

• for DataModel: /api/get/model/{name}/{level?}/{id}?apiKey=apiKeyValue. Parameter values are as follows:
  • {name} - a mandatory parameter. Represents the name of the Data Model (the Manage data model section in the admin panel).
  • {level?} - an optional parameter, which may be skipped (then the URL will look as follows: /api/get/model/{name}/{id}?apiKey=apiKeyValue). Represents an integer from 0 to infinity; equals to 1 by default. 0 - selects data from the main table without any joins. 1 - selects data from the main table and tables connected with it via Reference type attributes. 2 - selects data from the main table, connected tables, tables connected to them, etc.
  • {id} - primary key value.
  • apiKey - a mandatory parameter; the APIKey value specified in the system.
• for Mapping data model for a Form: /api/get/form/{name}/{id}?apiKey=apiKeyValue. Parameter values are as follows:
  • {name} - a mandatory parameter. Represents the name of the Form (the Manage forms section in the admin panel).
  • {id} - primary key value.
  • apiKey - a mandatory parameter; the APIKey value specified in the system.

These requests result in a following JSON:

{
    success: true/false,
    error: "",
    message: "",
    data: [{...}]
}

Upon a successful request success will be true, error and message values will be empty and can be ignored. data will contain an array of 0 or 1 elements: 0 elements if the object with the specified key was not found, 1 element if it was found. The names of object fields equal to their names in Data model or Mapping data model for a Form.

In case of an error, success will be false, error will contain the text of the error, and message will contain a stacktrace of the exception thrown.

Complex Form or DataModel request

Selection with a complex filter and/or sorting and paging is and HTTP POST method. To do that you need to form the following URL:

• for DataModel: /api/get/model/{name}/{level?}?apiKey=apiKeyValue. Parameter values are as follows:
  • {name} - a mandatory parameter. Represents the name of the Data Model (the Manage data model section in the admin panel).
  • {level?} - an optional parameter, which may be skipped (then the URL will look as follows: /api/get/model/{name}?apiKey=apiKeyValue). Represents an integer from 0 to infinity; equals to 1 by default. 0 - selects data from the main table without any joins. 1 - selects data from the main table and tables connected with it via Reference type attributes. 2 - selects data from the main table, connected tables, tables connected to them, etc.
  • apiKey - a mandatory parameter; the APIKey value specified in the system.
• for Mapping data model for a Form: /api/get/form/{name}?apiKey=apiKeyValue. Parameter values are as follows:
  • {name} - a mandatory parameter. Represents the name of the Form (the Manage forms section in the admin panel).
  • apiKey - a mandatory parameter; the APIKey value specified in the system.

You need to convey the following JSON request object (Content-Type = application/json) in the request body:

{
    filter : [{
        columns : ["Attribute1", "Attribute2"],
        term: "<=", // A list described below
        value: ""
    }],
    order :[{
        column : "Attribute1",
        order: "ASC or DESC"
    }],
    skip: 1,
    take: 10
}

All fields in the JSON request object are optional and can be specified in any combination.

• filter - filter elements array. All elements in the resulting filter will be concatenated with AND. Each filter element contains the following mandatory fields:
  • columns - array with column (attribute) names. Should contain at least one column; if there are several columns then they are concatenated with OR.
  • term - comparison criterion. Possible values are:
    • "=", "!=", ">=", "<=", "<", ">".
    • like - same as like ("%value%").
    • *like - same as like ("%value").
    • like* - same as like ("value%").
  • value - comparison value represented by a string.
• order - sort elements array. Each sort element contains the following mandatory fields.
  • column - name of a column (attribute) to be sorted against.
  • order - sorting order (ASC or DESC).
• skip - a number of records to be skipped in the selection.
• take - maximum number of records returned.

These requests result in a following JSON:

{
    success: true/false,
    error: "",
    message: "",
    data: [{...}]
}

Returned fields are described in the section above.

Changing data

Inserting and updating data is and HTTP POST method. To do that you need to form the following URL:

• for DataModel: /api/change/model/{name}?apiKey=apiKeyValue. Parameter values are as follows:
  • {name} - a mandatory parameter. Represents the name of the Data Model (the Manage data model section in the admin panel).
  • apiKey - a mandatory parameter; the APIKey value specified in the system.
• for Mapping data model for a Form: /api/get/form/{name}?apiKey=apiKeyValue. Parameter values are as follows:
  • {name} - a mandatory parameter. Represents the name of the Form (the Manage forms section in the admin panel).
  • apiKey - a mandatory parameter; the APIKey value specified in the system.

You need to convey the following JSON request object (Content-Type = application/json) in the request body:

{
    data: [{...}, {...}]
}

The data field should contain an array of objects to be inserted and/or updated. You can mix inserted and updated objects. In order to update data on the basis of Mapping data model for a Form you can specify collections. The names should correspond to those, specified in the Data Model or the Mapping data model. Keep in mind, that DWKit updates only those fields that belong to the main table or collection; in other words, you cannot update or insert fields with a join. Here's what a sample insert object looks like:

{
    Id : "client_1",
    Attribute1: 12,
    Attribute2: "Some string",
    Collection1 : [
        {Id: "client_1_1", Attribute1: "Some String" },
        {Id: "client_1_2", Attribute1: "Some String" }
    ]
}

Here's what a sample update object looks like:

{
    Id : "a482569d-2b3c-4d6e-9f45-05dec4a8162c",
    Attribute1: 12,
    Attribute2: "Some string",
    Collection1 : [
        {Id: "client_1_1", Attribute1: "Some String" },
        {Id: "b754fecc-8f34-49d0-9abf-1244985f4a14", Attribute1: "Some String" }
    ]
}

You can set the primary key value for new (inserted) records in two ways:

• with a string starting with "client_". Then, the response will correspond to the client key and database key
• with a valid value of the primary key the record will be inserted, but no correspondence shall occur.

The following rule applies to collections: the collection shall be replaced in full, collection elements absent in the payload will be deleted. This is identical to how DWKit works with forms.

These requests result in a following JSON:

{
    success: true/false,
    error: "",
    message: "",
    data: {
        inserted: 2,
        updated: 4,
        originalIds: ["client_1", "client_2"],
        insertedIds: ["a482569d-2b3c-4d6e-9f45-05dec4a8162c", "b754fecc-8f34-49d0-9abf-1244985f4a14"]
    }
}

Upon a successful request success will be true, error and message values will be empty and can be ignored. data will contain information on the operation:

• inserted - the number of inserted main records. Collections are excluded.
• updated - the number of updated main records. Collections are excluded.
• originalIds and insertedIds - set correspondence between client primary keys and primary keys of records inserted into the database.

In case of an error, success will be false, error will contain the text of the error, and message will contain a stacktrace of the exception thrown.

Deleting data

Deleting data by id

Deleting data by primary key is an HTTP POST method. To do that you need to form the following URL:

• for DataModel: /api/delete/model/{name}/{id}?apiKey=apiKeyValue. Parameter values are as follows:
  • {name} - a mandatory parameter. Represents the name of the Data Model (the Manage data model section in the admin panel).
  • {id} - primary key value.
  • apiKey - a mandatory parameter; the APIKey value specified in the system.
• for Mapping data model for a Form: /api/delete/form/{name}/{id}?apiKey=apiKeyValue. Parameter values are as follows:
  • {name} - a mandatory parameter. Represents the name of the Form (the Manage forms section in the admin panel).
  • {id} - primary key value.
  • apiKey - a mandatory parameter; the APIKey value specified in the system.

These requests do not have a body. They result in a following JSON:

{
    success: true/false,
    error: "",
    message: "",
    data: {
        deleted: 2
    }
}

Upon a successful request success will be true, error and message values will be empty and can be ignored. data will contain information on the operation:

• deleted - the number of deleted main records.

In case of an error, success will be false, error will contain the text of the error, and message will contain a stacktrace of the exception thrown.

Deleting data by id list or filter

Deleting data by id list or filter is an HTTP POST method. To do that you need to form the following URL:

• for DataModel: /api/delete/model/{name}?apiKey=apiKeyValue. Parameter values are as follows:
  • {name} - a mandatory parameter. Represents the name of the Data Model (the Manage data model section in the admin panel).
  • apiKey - a mandatory parameter; the APIKey value specified in the system.
• for Mapping data model for a Form: /api/delete/form/{name}?apiKey=apiKeyValue. Parameter values are as follows:
  • {name} - a mandatory parameter. Represents the name of the Form (the Manage forms section in the admin panel).
  • apiKey - a mandatory parameter; the APIKey value specified in the system.

You need to convey the following JSON request object (Content-Type = application/json) in the request body:

{
    filter : [{
        columns : ["Attribute1", "Attribute2"],
        term: "<=",
        value: ""
    }],
    ids : ["a482569d-2b3c-4d6e-9f45-05dec4a8162c", "b754fecc-8f34-49d0-9abf-1244985f4a14"]
}

You should specify either filter or ids for deletion request object.

• filter - the structure and logic is identical to data request filter. Filtered records will be deleted.
• ids - a list of primary keys of records for deletion.

These requests result in a JSON identical to the one returned when deleting a record by primary key.

Generating Swagger specification for Integration API and automatic client generation

The structure of objects conveyed to change requests and returned by get requests depends on your Data Model and/or Mapping data model for a Form. The system may contain tens and thousands of such objects, and it is extremely resource-consuming to describe them manually. For this reason, DWKit comes with an ability to automatically generate Swagger specification (Swagger 2.0), which allows you to generate a client to access DWKit's Integration API in under 5 minutes.

Swagger specification generation requests

IntegrationApiController has a method that returns swagger specification in yaml.

[Authorize]
[Route("swagger/{mode?}/{name?}")]
[HttpGet]
public async Task<ActionResult> GetSwaggerFile()
{
    try
    {
        var swagger = await IntegrationApiHttp.GetSwaggerSpecsAsync(HttpContext.Request);
        var filename = "dwkit.yaml";
        var contentType = "application/yaml";

        return File(Encoding.UTF8.GetBytes(swagger), contentType, filename);
    }
    catch (Exception ex)
    {
        return Json(new FailResponse(ex));
    }
}

You can get a Swagger specification file with the following GET requests:

• /swagger - will generate the description of access methods (get/change/delete) for all Data Model and Mapping data model objects in the system.
• /swagger/form - will generate the description of access methods (get/change/delete) for all Mapping data model objects in the system.
• /swagger/model - will generate the description of access methods (get/change/delete) for all Data Model objects in the system.
• /swagger/form/{name} - will generate the description of access methods (get/change/delete) for a Mapping data model object with the name name attached to a form.
• /swagger/model/{name} - will generate the description of access methods (get/change/delete) for a Data model object with the name name.

The button executing the /swagger request, i.e. getting description of all system objects, can be found on the Dashboard page of the admin panel.

Automatic generation of Integration API access client

The sequence of actions is as follows:

• Generate the Swagger description by using one of the GET methods described in the previous section. You will get a dwkit.yaml file.
• Do not forget to specify the APIKey in the admin panel.
• Go to Swagger Editor.
• Upload the dwkit.yaml file. Probably, at this point you will not see the Generate Client and Generate Server options in the menu, or you will not be able to download the generated file. To fix that you need to allow the execution of unsafe scripts in your browser.
• Select the respective technology in the dropdown list of the Generate Client menu. For .NET this is either csharp or csharp-dotnet2.
• The .zip client will be generated and downloads.

Afterwards you can use the client to access Integration API without additional settings.