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:8080/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.
applicationName The name of the application that the sessions will be connected to.
connectionPool Optional connection pool.
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.

  session_inactive_expiration_minutes Defines timeout for inactivity. If a value greater than 0 is entered, the session will be timed out. For example, with the following setting a user inactive for 5 minutes will be disconnected automatically:
"session_inactive_expiration_minutes": 5
  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:8080/applinx/rest/session

    Request Body:

    {
      "naturalUsername": "string", (required for Natural hosts)
      "naturalPassword": "string", (required for Natural hosts)
      "redirectAfterLogin": true/false, (optional)
      "sessionDescription": "string" (optional)
    }

    Notes:

    1. Parameters naturalUsername and naturalPassword are required only if you configured hostAuth as your authentication mode. See Host Authentication.
    2. Parameter redirectAfterLogin applies to OpenID Connect authentication only. If set to true, you will be redirected to your client application after a successful login. This is required to configure client_app_uri in the configuration file.

    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:

    {
      "message": "Connected", 
      "redirect_uri": "http://openidconnect.com?adad?123"
    }

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

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"
      }
    }

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.

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 The ApplinX REST API session endpoint.
    client_app_uri Your client application URI to which you will be redirected after a successful login to your third-party OIDC provider.

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, a new session will be created.

  4. If you set redirectAfterLogin to true, you will be redirected to the client application you configured under client_app_uri. See Configuring OpenID Connect Authentication.
    Otherwise you will get a JSON message saying the session has connected.

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".