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:
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.
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.
Note: |
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 |
This section covers the following topics:
To 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:
naturalUsername and naturalPassword are required only if you configured hostAuth as your authentication mode. See Host Authentication.
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.
To disconnect a session
Send a DELETE request to the following URL:
http://{host}:{port}/applinx/rest/sessionWhen 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.
To 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"
}
}
To 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.
To 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.
The ApplinX REST API supports the following authentication modes:
To 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.
This authentication mode uses a third-party LDAP server.
To 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:
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.
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.
To 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. |
For this example, three groups (Supervisors, Developers, Users) were created in Okta. The Everyone group is available out-of-the-box.
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.
Here is the configuration of the group claim:
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:
Like the first example, we created three groups here as well:
The flow of a Create Session Request when using OpenID Connect authentication is somewhat different.
To create a session
Send a regular POST request to the session endpoint, for example
http://{host}:{port}/applinx/rest/sessionYou will receive a JSON response containing the variable redirect_uri. For example:
This link will send you to authenticate against your OIDC provider.
Enter your credentials and confirm to create a new session, for example:
If your credentials are valid, a new session will be created.
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.
This authentication mode is used for hosts such as Natural-UNIX that already have an authentication step.
To configure Host Authentication
In the the rest-api-config.json configuration file, set security parameter auth to "hostAuth".
In the request body, send the host credentials in order to connect a session:
"naturalUsername": "string", "naturalPassword": "string",
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.
To disable authentication
In the the rest-api-config.json configuration file, set security parameter auth to "disabled".