Introduction

HORISEN apps can show data from external APIs (Client API). All integration points must be pre-configured in the local integration storage and considered static meta/configuration data. The only data Client API needs to provide dynamically is actual raw JSON data for UI components. Each time a front-end app makes a request to see the data, the Integration proxy makes a call to Client API to provide the data.

To be able to display data from the Client API in the application, that API has to meet some requirements about authentication between Client API and IPA (Integration Proxy API), query parameters, pagination structure, columns for the grid components, and properties for the KPIs.

1. Authentication

It is recommended to have some sort of authentication on the Client API side (but it can be public too), and right now IPA supports only lifetime access token which can be sent in the URL as a token query parameter or in a request header where header key and header value are completely configurable.

2. Client API

The client API basically needs to provide a single endpoint to respond with raw json data. The URL is not strict, the client can decide to set up some params as path variables to query params. The overall URL is defined in the format e.g.:

https://api.client.com/components/{componentId}?type={componentType}&token={token}&language={language}&locale={locale}&referenceId={referenceId}&var1=val1&pageNumber={pageNumber}&pageSize={pageSize}&sort={sort}

The Variables are:

• referenceId - this is an ID of an account on the client's side, e.g. billing account ID, or whatever identifies data to be presented.
• componentId - identifies data for particular integration component, e.g. invoices grid, or KPI data.
• componentType - grid or KPI.
• token - is the authorization token for API integration. It can be configured to be sent as HTTP header instead of query param.
• language - if client wants to return language aware content.
• locale - if client want to return locale aware content.
• pageNumber, pagesize - pagination parameters (grid only).
• sort - is optional sort ordering value, eg: sort=column1,-column2 which means sort by column1 ASC and by column2 DESC (grid only).

Since different components (componentType) are expected to return different payloads, it might be more practical to have separate endpoints for each component. Please check our IPA Mock API as an example, presented in UI Integration API section. Since our endpoint format is flexible enough, those cases can be configured as:

https://api.client.com/components/{componentType}s/{componentId}...

3. Grid Component

Grid component is a type of UI component where data is displayed in a table. The grid component supports pagination, columns filtering, and columns sorting which are explained in detail below. Each option for the grid (paging, filtering, sorting) is sent to the Client API as a query parameter. It's expected that the Client API does server-side sorting/filtering and pagination.

Pagination query parameters:

• pageNumber - number of a page,
• pageSize - items per page.

Sortable columns query parameters:

Each column in the grid can be sortable, and it is also supported multiple columns sorting (e.g. id and title are sortable columns):

• sort=id,-title - should return data ordered ascending for id column and ordered descending for the title column.

Filterable columns query parameters:

Each column in the grid can be filterable with various type of operations:

• Value Operators:

  • isnull - Is Null
  • isnotnull - Is not Null
  • isempty - Is Empty
  • isnotempty - Is not Empty

• String Operators:

  • eq - Is Equal To
  • neq - Not Equals To
  • startswith - Starts With
  • contains - Contains
  • endswith - Ends With
  • doesnotcontain - Does Not Contain

• Numeric Operators:

  • eq - Is Equal To
  • neq - Not Equals To
  • lt - Less Than
  • lte - Less Than or Equal
  • gte - Greater Than or Equal
  • gt - Greater Than

• Range Operators:

  • in - In an array of values
  • notin - Not In an array of values
  • between - Between values
  • notbetween - Not Between values

• Example:

  • id is 5
    eq(id)=5 or id=5
  • and title contains John
    contains(title)=John
  • and title does not contain Doe
    doesnotcontain(title)=Doe
  • and parent is not null:
    isnotnull(parent)=true
  • and status is in [active, pending]
    in(status)=active,pending

Filter query parameters are sent automatically, and their parameter names cannot be reconfigured. E.g. if an end-user wants to filter rows to contain only the ones where column1 contains "Test" works, param contains(column1)=Test will be sent.

The grid component response:

The response from the Client API has to be compatible with the IPA configuration and grid component by returning a data array with grid items and meta object with pagination object. The example for the grid response can be found in the IPA Mock API description (UI Integration API).

Pagination object must have these properties:

• total - total number of items.
• count - number of returned items.
• perPage - selected option in the grid.
• currentPage - number of a page.
• totalPages - total number of pages.
• links - this is an object with next and/or previous links.

Data is an array of objects that represents the data that will be displayed in a grid. Properties of the data object must be in direct relation with the name and type of the columns in the IPA config.

Example:

{
    "data": [
        {
            "id": 3275,
            "invoiceDate": "2018-01-23",
            "invoiceDateTime": "2018-01-23T09:40:16Z",
            "url": "https://horisen.com"
        },
        {
            "id": 3276,
            "invoiceDate": "2018-01-24",
            "invoiceDateTime": "2018-01-24T10:42:16Z",
            "url": "https://horisen.com"
        },
 
        //...
    ],
    "meta": {
        "pagination": {
            "count": 10,
            "currentPage": 1,
            "perPage": 10,
            "total": 22,
            "totalPages": 3
        }
    }
}

4. KPI Component

KPI component is a type of UI component where single data is displayed in a box. The KPI component consists of:

• title - title for the component.
• value - value that is displayed in the component.
• link - URL that will be opened on a click.
• footer - a string that is displayed in the footer of the component.

This data must be returned by the Client API in a form of a single JSON object (the example can be found in the UI Integration API description.). For this type of component, there are no additional query parameters besides general parameters.

Example:

{
    "footer": "By More credit",
    "link": "https://www.horisen.com",
    "title": "Total",
    "value": "954.32"
}

An example of the Business Messenger application UI integration is presented on the following screenshot: