Create an API endpoint for an application

Starting situation

You use the "Task planning" application to manage your projects.

The "Task planning" application is one of the numerous application templates available free of charge in Intrexx. For more information, see the following sections:

There are three teams in your company: Finance, Marketing and Sales.

You (David Winter) are part of the Sales team.

Your team is currently working on the "New ERP" project. Three tasks have been created for your team. One task each has the status "Todo", "In progress" and "Completed".

Goal

As a member of the Sales team, you will be traveling a lot. You also want to get a quick overview of the teams on the go via a mobile app or other "external software". The solution for this is described in this tutorial.

You will create a REST interface for task scheduling with the Intrexx Application API. This provides all the data you require. They can then be consumed from an APP or cloud product.

The Intrexx Application API gives you the option of generating OpenAPI compatible documentation (Swagger documentation). You can use this to create an APP or pass it onto a third-party provider.

Tutorial content

This tutorial describes in detail how you can create a REST interface for the "Task planning" application in Intrexx. As part of the process, the required data group endpoints are created, the corresponding rights are assigned and an API key is generated for authentication.

It then describes how to generate the Swagger documentation.

In this tutorial, "Postman" is used as an API consumer to represent an app or a cloud product.

Preparatory tasks

  1. Create demo portal or import "Task planning" application into existing portal

    This tutorial describes how to create the REST API interface based on the Intrexx demo portal. You can find out how to create a new portal using the Intrexx demo portal as a template in the following section: Using Intrexx Demo Portal as a Portal Template

    Alternatively, you can also import the "Task planning" application template into an existing portal. The corresponding procedure is described in the following section: Importing online application templates.

  2. Create user "David Winter".

    In the tutorial, the user for the REST API interface is named David Winter. It has the "User" role.

    In the Intrexx demo portal, this user is created by default.

  3. Download Postman or use online

    Install the Postman Client or use "Postman for the Web".

Create data group endpoint - Read multiple records

Step-by-step guide

  1. Open the "Task management" application.

    Click on (Create new end point).

    In order for the "API endpoints" area to be displayed, you must activate the "API endpoints" checkbox in the main menu under "View" Activate "API endpoints" view.

    The "General" dialog step appears.

  2. Enter a name and description for the endpoint.

    The name must be unique, consist of at least two characters and start with a letter. Only alphanumeric characters, hyphens, underscores and periods are allowed.

    The texts captured in the dialogs enter the Swagger documentation. It is therefore very helpful for you and for a potential service provider if you choose descriptive names and follow a naming convention.

  3. Click on "Data group endpoint".

  4. Click on "Next".

    The "Data group selection" dialog step appears.

  5. In the "Action" selection field, select the value "Read multiple data records".

  6. Select the value "Team" in the "Data group" selection field.

Step-by-step guide

  1. Click on the icon.

    The "Add data fields" dialog box is displayed.

  2. Deactivate the "(PK) (S) (ID) <string>" checkbox.

  3. Select the following checkboxes:

    • Description <text>

    • Title <string>

    • Team leader - Full name <string>

  4. Click on "OK".

    You return to the "Data group selection" dialog step.

    The previously selected data fields are displayed in the "Request return values" area.

    For better readability of the return values and the Swagger documentation, we recommend that the return values are renamed.

  5. Select a return value in the "Request return values" area.

  6. In the right pane, enter a name and description for the return value.

    In our example, we use the "Camel notation". The first part of the name indicates the application or resource.

    • teamDescription

    • teamTitle

    • teamFullNameTeamLeader

  7. Rename all return values.

  8. Click on "Next".

    The "Path parameters" dialog box appears.

The specification of a path parameter is mandatory. We use a static parameter. We use the static path parameter to specify the resource.

Step-by-step guide

  1. Click on the icon.

  2. Click on "Static".

  3. Enter the name "taskmanagementTeams" and a descriptive name.

  4. Click on "Next".

    This takes you to the "Query parameters" dialog step.

In the Query parameters dialog step, no specifications or queries are required, since we want to determine all teams.

Click on "Next".

The "Filter and sort" dialog step appears.

In the "Filter and sorting" dialog step, we specify the sorting of the return values. It is to be done on the basis of the team title.

Step-by-step guide

  1. Click on the icon.

  2. Select "Team > Title <string>".

    The selected sort is displayed.

  3. If available, remove other sortings.

  4. Click on "Finish".

    The newly created endpoint is displayed in the "API endpoints" area.

  5. Click on the icon (publish application completely).

In this step, we grant the user David Winter the right to use the previously created endpoint.

In the following step, we assign the API key to the user David Winter, so that he has all the necessary rights to use the API endpoint.

Step-by-step guide

  1. Open the properties dialog of the "Task management" application.

    To do this, select the application and press "ENTER".

    Or

    Select the application and click the right mouse button.

    Click on "Properties" in the context menu.

    The "Properties - Application" dialog is displayed.

  2. Switch to the "Authorizations" tab.

  3. Switch to the "API endpoints" tab on the left-hand side.

    Select the endpoint "/taskmanagementTeams".

  4. Click on "Add".

    The "Add rights holder" dialog box appears.

  5. Select the user "David Winter".

  6. Click on "OK".

    The user "David Winter" is displayed.

    It has the "Use end point" right.

    Click on "OK".

    You will return to the application.

  7. Click on the icon (publish application completely).

Step-by-step guide

  1. Start the "Integration" module.

  2. Click on "Application-API" > "API-Keys".

  3. Right-click on "API keys without role".

    A context menu is displayed.

  4. Click on "Create new API key".

    The "Create new API key" dialog box is displayed.

  5. Enter a descriptive name for the API key in the "Name" field.

  6. Select the user "David Winter" in the "User" selection field.

  7. Activate the "Task planning" checkbox.

    This automatically enables the API endpoint as well.

  8. Click on "OK".

    The API key entry is displayed below "API keys without role".

Step-by-step guide

  1. Select the API key that you have created.

  2. Press the right mouse button.

    A context menu is displayed.

  3. Click Copy API Key.

    The API key is now on the clipboard.

    It is a good idea to insert the API key into Notepad, for example.

Step-by-step guide

  1. Start the "Integration" module.

  2. Click on "Application API" > "API endpoints".

  3. Select the application for which you want to create Swagger documentation.

  4. Right click on it.

    A context menu is displayed.

  5. Click on "Create Swagger documentation".

  6. Save the Swagger documentation.

    The Swagger documentation is stored in "yaml" format ("taskmanagement.yml").

Step-by-step guide

  1. Launch Postman.

  2. Click on the "APIs" menu item in the left-hand navigation area.

  3. Click on "Import".

    An import dialog is displayed.

  4. Select the previously saved .yml file ("taskmanagement.yml").

  5. Click on "Import".

    A dialog is displayed to confirm the import.

    The Intrexx API is displayed.

Step-by-step guide

  1. Click on the directory with the name of the imported Swagger documentation.

  2. Click on the "Authorization" tab.

  3. In the "Type" selection list, select the value "API Key" ().

  4. Enter the value "X-API-KEY" in the "Key" input field ().

  5. In the "Value" input field, enter the API key that you copied from Intrexx (see Step 8 - Copy API key)().

  6. In the "Add to" selection field, select the "Header" value ().

  7. Save the information.

Step-by-step guide

  1. Click on the API endpoint "Get-all-teams" ().

  2. On the "Params" tab, deactivate the query params KEYs (). (The settings are controlled by the Swagger documentation)

  3. Click on "Send".

    The return values you have defined are displayed under "Body".

    Display on the "Visualize" tab

    Postman offers the option of displaying the transmitted JSON data in HTML format via the "Visualize" tab.

    To do this, you must enter a corresponding code on the "Tests" tab (). Detailed information can be found under the following link: Postman Learning Center - Visualizing responses.

    If you then execute the request again and switch to the "Visualize" tab (), the data is displayed in the same way as it might be displayed in an app or in a cloud solution.

    Below you will find the code that was used in the "Tests" tab.

    pm.test("Status code is 200 and Present in Tabular form", function () {
    pm.response.to.have.status(200);
    let template = `
	<style type="text/css">
        .ixtable {font-size:14px;color:#ffffff;width:100%;border-width: 1px;border-color: #00a3c7;border-collapse: collapse;}
        .ixtable th {color: #ffffff;font-size:16px;background-color:#00a3c7;border-width: 1px;padding: 8px;border-style: solid;border-color: #87ceeb;text-align:left;}
        .ixtable tr {color:#2a2a2a;background-color:#ffffff;}
        .ixtable td {font-size:14px;border-width: 1px;padding: 8px;border-style: solid;border-color: #87ceeb;}
        .ixtable tr:hover {background-color:#e0ffff;}
    </style>
    <div>
        <table class="ixtable" border="1">
            <tr>
                <th>Name</th>
                <th>Teamleader</th>
                <th>Beschreibung</th>
            </tr>
            {{#each .}}
            <tr>
                <td>{{teamTitle}}</td>
                <td>{{teamFullNameTeamLeader}}</td>
                <td>{{teamDescription}}</td>
            </tr>
            {{/each}}
        </table>
    </div>`;
    let response = pm.response.json();
    pm.visualizer.set(template, response.data);
});

More information