Using the ApplinX REST API

Using the ApplinX REST API you can create and disconnect a session, get a screen and update a screen. Four authentication modes are provided to call the API: ApplinX, LDAP, OpenID Connect and Host Authentication. This document covers the following topics:


Getting Started

You can get the API description (based on the OpenAPI Specification) of the REST API by sending a GET request to the following URL:

http://{host}:{port}/applinx/rest/swagger.json

Example:

http://localhost:2380/applinx/rest/swagger.json

We recommended you paste the response output in the Swagger Editor in the following URL:

https://editor.swagger.io/

This gives you all the information about the operations and models of the API, as well as generating an out-of-the-box new client (in your favorite language) that consumes the API.

Configuration

The ApplinX REST API contains a configuration file rest-api-config.json in folder WEB-INF\config. Use this file to define the configuration parameters:

Parameter Description
serverURL ApplinX server URL.
applications Names of applications that the sessions can be connected to.
security  
  auth Four authentication modes are supported. These are described in more detail below.
  • ApplinX Authentication (using the ApplinX Administator)

  • LDAP

  • OpenID Connect

  • Host Authentication, for hosts such as Natural-UNIX that already have an authentication step

Note:
You can also disable authentication with setting auth=disabled.

  groups Defines groups for different user types.
    admins_group  
    developers_group
    users_group

Session Management

This section covers the following topics:

Creating a Session

Start of instruction setTo create a session (connection)

  • Send a POST request to the following URL:

    http://{host}:{port}/{basePath}/rest/session

    For example:

    http://localhost:2380/applinx/rest/session

    Request Body:

    {
    
    "applicationName": "string", (name of application that the session will be connected to) 
    "connectionPool": "string", (Optional)
    "sessionDescription": "string"(Optional) 
     "naturalUsername": "string", (required for Natural hosts).
     "naturalPassword": "string", (required for Natural hosts).
    "naturalNewPassword": "string", (fill this if you'd like to change the host password).
    "failOnWarning": boolean, (don't connect session if getting a warning when trying)
     "options": {  (Optional GXBaseObjectConstants)
       "additionalProp1": "string",
       "additionalProp2": "string",
    }, }

    Notes:

    1. Parameters naturalUsername and naturalPassword are required only if you configured hostAuth as your authentication mode. See Host Authentication.
    2. See the available BaseObject constants which apply to the options parameter: GXBaseObjectConstants

    Authorization Header:

    If you are using ApplinX's Administrator or LDAP authentication, add Basic Auth schema to the Authorization header.
    Example:

    "Basic lfhsdadkankdnaadacxzczca"

    The second word in the string is you username/password encoded in Base64. For example, in JavaScript use

    var auth = 'Basic ' + btoa(username + ':' + password); 

    and add the auth string to the Authorization header of the request.

    Response Body:

    {
     "token": "string", 
     "keyboardMapping": [
       {
         "keyCode": 0,
         "additionalKey": 0,
         "targetFunction": "string"
       }
     ],
     "message": "string",
     "redirectUri": "string"
    }

    Note:
    "redirect_uri" will be returned only if using OpenID Connect authentication. See OpenID Connect Authentication.

    Important:
    The response body contains a variable called 'token'. This token represents your session and will be used in all subsequent requests. The token should be added to the authorization header using bearer token schema.

    Example:

    var auth = "Bearer <token>"

    Replace <token> with your token value and add the auth string to the Authorization header of all subsequent requests.

Start of instruction setTo disconnect a session

  • Send a DELETE request to the following URL:

    http://{host}:{port}/applinx/rest/session

Getting the Current Screen

When a connection is established, using the create session request, you can get the current screen, as well as update the screen and navigate to the next.

Start of instruction setTo get the current screen

  • Send a POST request to the following URL:

    http://{host}:{port}/applinx/rest/screen

    Request Body:

    options are optional key-value pairs, for example:

    {
      "options": {
        "GX_VAR_TRIM_FIELDS": "none",
        "GX_VAR_TRIM_MODE": "bothSides"
      }
    }

Note:
See Important Note on adding the token in the authentication header under Creating a Session

Updating the Current Screen

Start of instruction setTo update the current screen and navigate to the next

  • Send PUT request to the following URL:

     http://{host}:{port}/applinx/rest/screen

    Request body (required):

    {
      "fields": [
        {
          "name": "string", // name is interchangeable with position (see below).
          "value": "string", (required)
          "index": 0, (Only for multiple field)
          "position": { // if the field has name, position is interchangeable with name.
            "column": 0,
            "row": 0
          }
        }
      ],
      "sendKey": "string",
      "cursor": {
        "fieldName": "string", (optional, interchangeable with position).
        "position": {
          "column": 0,
          "row": 0
        }
      }
    }

    Example 1:

    {
      "fields": [
        {
          "value": "Hello World!",
          "position": {
            "column": 15,
            "row": 21
          }
        }
      ],
      "sendKey": "[enter]",
      "cursor": {
        "position": {
          "column": 11,
          "row": 3
        }
      }
    }

    Example 2:

    {
      "fields": [
        {
          "name": "FIELD02",
          "value": "Hello world!",
        }
      ],
      "sendKey": "[enter]",
      "cursor": {
        "fieldName": "FIELD03"
      }
    }

    Request header:

    Screen ID (required)

    The current screen ID obtained in a get screen response.

Start of instruction setTo get information on whether there is a session connected and the authentication mode defined in the configuration file

  • Send a GET request to the following URL: http://{host}:{port}/applinx/rest/info.

Note:
See Important Note on adding the token in the authentication header under Creating a Session

Web Application Logging

One of the REST API purposes is to be used by a web application. Sometimes, complex web applications need to monitor the front-end application and the web pages on the server-side because web browsers cannot directly log messages to a file on a local machine. The REST API exposes an endpoint that enables web applications to send logs from the browser to file under ApplinX installation folder through an HTTP call. The log file, javascript_log.txt, is placed in the installation folder SoftwareAG/ApplinX/log.

Start of instruction setTo log a message

  • Send a POST request to the following URL:

    http://localhost:2323/applinx/rest/logger

    Request body:

    {
       "timestamp": "string",
       "level": 0,
       "fileName": "string",
       "lineNumber": "string",
       "message": "string"
       "additional": [
         "string"
       ],
    }
    • The fileName and lineNumber parameters correspond to the JavaScript file after compilation.

    • You can send any additional data with the additionalData parameter. The additional data will be aggregated and shown in the log output.

    Sample output in javascript_log.txt:

    Date and time of event        level     filename:line   username         session ID                                                              message         additional data
    |-------------------------||------||------------||--------------||-----------------------------------------|-----------||-------------------------------|
    2021-03-24T09:45:30,883 FATAL [main.js:3608][administrator][398FD26A58C9774CEBD6EE9A0CC059DF] hello world data1, data2, data3, data4 ........

Authentication

The ApplinX REST API supports the following authentication modes:

ApplinX Authentication

Start of instruction setTo configure ApplinX authentication

  • In the the configuration file rest-api-config.json configuration file, set security parameter auth to "applinx". Example:

    {
      "serverURL": "applinx://localhost:2323",
      "applicationName": "InstantDemo",
      "security" : {
          "auth" : "applinx",
          "groups" : {
              "admins_group" : "Supervisors",
              "developers_group" : "Developers",
              "users_group" : "Everyone",
          }
      }
    }

    Note:
    Authentication of type applinx uses the users and groups from the ApplinX Administrator tool.

LDAP Authentication

This authentication mode uses a third-party LDAP server.

Start of instruction setTo configure LDAP authentication

  • In the the configuration file rest-api-config.json configuration file, set security parameter auth to "ldap" and provide the LDAP environment variables. Example:

    {
        "serverURL": "applinx://localhost:2323",
        "applicationName": "InstantDemo",
        "security": {
            "auth": "ldap",
            "groups": {
                "admins_group": "APX_Admins",
                "developers_group": "APX_Developers",
                "users_group": "APX_Users"
            },
            "ldap": {
                "url": "ldap://localhost:123",
                "dn": "cn=admin,dc=test,dc=apx,dc=eur,dc=ad,dc=sag",
                "password": "passwordExample",
                "authentication": "simple",
                "filter_user": "(uid={})",
                "filter_admins_group": "(&(cn=APX_Admins)(memberUid={}))",
                "filter_developers_group": "(&(cn=APX_Developers)(memberUid={}))",
                "filter_users_group": "(&(cn=APX_Users)(memberUid={}))",
                "context_users": "dc=test,dc=apx,dc=eur,dc=ad,dc=sag",
                "context_groups": "dc=test,dc=apx,dc=eur,dc=ad,dc=sag"
            }
        }
    }
    LDAP Environment Variable Description
    url The LDAP server's address.
    dn The DN of read-only account, if not anonymous.
    password The password of read-only account, if not anonymous.
    authentication Either "simple" if a read-only search account is required, or "none" if anonymous.
    filter_user Filter to find user's record; note that {} is replaced by the user-supplied ID.
    filter_admins_group, filter_developers_group, filter_users_group These are filters for our three application roles... You might have to use 'member' instead of 'memberUid'.
    context_users Optional path to start the user search somewhere more specific than the root.
    context_groups Optional path to start the group search somewhere more specific than the root.

    This is the LDAP server we connected to in the above example, showing the context of the groups and users:

    graphics/restApi_authentication_ldap.png

After everything has been configured in the configuration file, the end users log in by sending their username (which in this example is the uid we configured inside the filter_user parameter) and password.

graphics/restApi_authentication_ldap-2.png

In this example we have a user with User Name "acohen". To log this user in, send acohen:pass. Send the username:password in the Authorization Header of the create session request.

OpenID Connect Authentication

Configuring OpenID Connect Authentication

Start of instruction setTo configure OpenID Connect authentication

  • In the the configuration file rest-api-config.json configuration file, set security parameter auth to "oidc" and provide the OpenID Connect environment variables.

    OpenID Connect
    Environment Variable
    Description
    authorization_endpoint The client sends the end-user's browser here to request the user's authentication and consent. This endpoint is used in the code and implicit OAuth 2.0 flows that require end-user interaction.
    token_endpoint Post an OAuth 2.0 grant (code, refresh token, resource owner password credentials, client credentials) to obtain an ID and/or access token.
    userinfo_endpoint Retrieve profile information and other attributes for a logged-in end-user.
    client_secret The client secret, which you get from your OpenID Connect provider.
    client_id The client ID, which you get from your OpenID Connect provider.
    redirect_uri Optional. The redirect_uri specified in your ID provider configuration.

Example using Account Created in Okta

graphics/restApi_authentication_oidc.png

For this example, three groups (Supervisors, Developers, Users) were created in Okta. The Everyone group is available out-of-the-box.

graphics/restApi_authentication_oidc-2.png

For this example, a custom group claim was also created. This will be returned in the ID token. This means that the REST API will know which group the user (who is trying to authenticate) belongs to.

graphics/restApi_authentication_oidc-3.png

Here is the configuration of the group claim:

graphics/restApi_authentication_oidc-4.png

Example using Account on Keycloak

This second example uses an account created on Keycloak. In Keycloak we get the groups out-of-the-box, so there is no need to create a custom groups claim we did in the first example. Keycloak configuration:

graphics/restApi_authentication_oidc-5.png

Like the first example, we created three groups here as well:

graphics/restApi_authentication_oidc-6.png

Connecting an ApplinX Session and Authenticating with OpenID Connect

The flow of a Create Session Request when using OpenID Connect authentication is somewhat different.

Start of instruction setTo create a session

  1. Send a regular POST request to the session endpoint, for example

    http://{host}:{port}/applinx/rest/session
  2. You will receive a JSON response containing the variable redirect_uri. For example:

    graphics/restApi_authentication_oidc-7.png

    This link will send you to authenticate against your OIDC provider.

  3. Enter your credentials and confirm to create a new session, for example:

    graphics/restApi_authentication_oidc-8.png

    If your credentials are valid, you will be redirected from the login page to your 'redirect_uri' with a one-time code, which will placed as a query parameter.

  4. Send a request to the REST API connect session endpoint with the code as a query parameter and a new session will be connected. You should also send request body that contains the application name to connect to. See Creating a Session.

Host Authentication

This authentication mode is used for hosts such as Natural-UNIX that already have an authentication step.

Start of instruction setTo configure Host Authentication

  1. In the the rest-api-config.json configuration file, set security parameter auth to "hostAuth".

  2. In the request body, send the host credentials in order to connect a session:

    "naturalUsername": "string",
    "naturalPassword": "string",
    

Disabled

This authentication mode (no authentication) is used for hosts that have a screen containing an authentication step. This mode means you can disable the additional third-party authenticator. This setting is also useful if you do not want authentication before creating a session.

Start of instruction setTo disable authentication

  • In the the rest-api-config.json configuration file, set security parameter auth to "disabled".

Executing a Procedure

This section covers the following topics:

For information on procedure entities and procedure groups, see Procedures

Introduction

With the REST API you can publish procedures as REST endpoints and then execute the procedures, using an HTTP call with JSON request body containing the Procedure inputs, and a JSON response body representing the Procedure outputs. The procedure I/O outputs are defined in the Designer when you create a procedure.

Start of instruction setTo publish a procedure as a REST API endpoint

  1. Assign the procedure to a Procedure Group. See Designing and Developing an Application > ApplinX Entities > Procedure Groups (used as Service Providers) > Assigning a Procedure to a Procedure Group.

  2. Configure the application that contains the procedure group in the REST API configuration file (rest-api-config.json) as application in the 'applications' array.

  3. Restart the ApplinX server. We recommend you add all your procedures at the same time so you only need to restart to restart your server once.

When a Procedure is published as a REST API endpoint, the OpenAPI documentation of the REST API will contain all the information about the procedure endpoint (Request and response body schema, Authentication schema, HTTP method). See Getting Started

Path Procedure Endpoints

Path Procedures expose two types of endpoints:

A stateful endpoint has the suffix '/Stateful'; a stateless endpoint does not have a special suffix. Other procedure types (Flow, Web, Program) exposing only one endpoint (stateless). Your Open API documentation will contain documentation about the two endpoints.

Stateless

A stateless procedure execution does not require a session. You can send a procedure call through the REST endpoint, get the output and no session remains open.

Start of instruction setTo execute a stateless Procedure

  • Add your authentication credentials to the request (unless configured with OpenID Connect.

Note:
The basic ApplinX and LDAP authentication methods require simple username and password that is sent from the end user to the ApplinX REST API. In OIDC, however, end users do not send their credentials directly to ApplinX. Instead, a third-party ID provider ((Okta, Keycloak, etc...) is used for authentication. A code is sent and then verified in the ApplinX REST API. If verification is successful, the REST API returns a session token that will be used by the user in all subsequent requests. This token represents a session within the REST API. So when you want to execute a stateless procedure with OpenID Connect you need to connect a session, receive a session token and send the token in the subsequent procedure call request.

Stateful

Stateful procedure execution requires an established session context, the procedure is executed on the session and the session remains connected after the procedure run is finished.

Start of instruction setTo execute a stateful procedure

  • Add the authorization token you received within the response of the HTTP call to the endpoint of connect session service.

Procedure REST Endpoints Structure

When a Procedure is assigned to a Procedure Group, it is deployed dynamically as a REST service. The endpoint of the REST service is structured according to the name of the application, procedure group and procedure in this exact order. See sample URL:

http://localhost:2380/applinx/rest/procedures/myAppName/myProcedureGroupName/myprocedureName

If the Procedure is of type 'Path Procedure', an additional endpoint is created with suffix '/Stateful'. See sample URL:

http://localhost:2380/applinx/rest/procedures/myAppName/myProcedureGroupName/myprocedureName/Stateful

The following is an example of two published endpoints for Path Procedure in the Swagger Editor:

graphics/restApi_executeProc_structure.png

Notes:

  1. This endpoint is created for Procedure 'GetCustomerByID' within Procedure Group 'DEMOINS' inside application 'SOADemo'.
  2. Every Procedure endpoint has the prefix '/procedures'.