Create an API Endpoint for an Application - Advanced

Contents of this tutorial

This tutorial describes two slightly more advanced use cases for creating API endpoints. The goal here is to limit or filter the values returned in response to a request.

In the first use case, this is still done "statically." In other words, we specify a particular team from the task management system for which all tasks—sorted by project—will be returned.

In the second use case, the values are returned "dynamically." This means that the user or consumer of the API endpoint can enter or select any team from the task management system. The tasks assigned to this team—organized by project—are then returned.

For the restrictions and selections described here, we will use the filter dialog in one case and the "Query Parameters" dialog step in the other.

Preparatory Activities

This "Advanced Tutorial" builds on the tutorial "Create an API endpoint for an application." It is helpful to first recreate the use case described there.

For the Advanced Tutorial, you must complete the same preparatory steps as for the tutorial "Create an API endpoint for an application":

1. Create a demo portal or import the "Task Planning" application into an existing portal

   This tutorial describes how to create a REST API 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 the Intrexx Demo Portal as a Portal Template

   Alternatively, you can also use the application template "Import Task Planning into an Existing Portal." The procedure is described in the following section: Import Online Application Templates.

2. Create the user "David Winter."

   In the tutorial, the user who is supposed to use the REST API is named David Winter. He has the "User" role.

   This user is created by default in the Intrexx Demo Portal.

3. Download Postman or use it online

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

   • https://www.postman.com/

   • https://web.postman.co

 

Identify the tasks of a specific team

Requirement

You want to get an overview of all your team's tasks. To do this, you would like to request the following information:

• Team Name

• Project Title

• Titles of the Assignments

• Task Status

The "Task" data group contains all the data fields needed to retrieve the desired information. However, the "Title" data field is more directly associated with the "Task" data group. It contains the title of the assignment. The other data fields are referenced in the "Task" data group from the "Team," "Project," and "Status" data groups.

Procedure

Step-by-Step

To get an overview of all the tasks handled by the "Sales" team, follow these steps:

1. Create a new endpoint and give it a descriptive name.

2. Click "Data Group Endpoint."

3. Click "Next."

   You will be taken to the "Data Group Selection" dialog step.

4. In the "Action" drop-down menu, select "Read multiple records."

5. In the "Application" drop-down menu, select "(current application)."

6. In the "Data Group" drop-down menu, select "Task."

7. Click the " " icon.

8. Uncheck the checkbox "(PK) (S) (ID) <string>"

Select Data Fields

9. In the "Add Data Fields" dialog box, select the following data fields:

   • Title <string>

   • Project - Title <string>

   • Status - Title <string>

   • Team - Title <string>

   To make the return values and the Swagger documentation easier to read, it is recommended that you rename the return values.

   For this tutorial, the return values have been renamed as follows:

   • title (Title <string>) → taskTitle

   • ref4125cc5b (Title <string>) → taskStatus

   • ref0542049e (Title <string>) → teamTitle

   • ref5477b5f9 (Title <string>) → titleProject

   

   Names of referenced data fields

   The names of the data fields referenced in the "Task" data group correspond to the names of the reference fields. You can view these in Intrexx Expert Mode (Expert Mode). To do this, select the data group. Right-click. From the context menu, select "Show Data Fields." Select the referenced data field. Right-click. Select "Properties" from the context menu. Switch to the "Expert" tab.

   

   Add data fields one after another

   You can add the data fields one after another and rename each newly added field.

10. Click "Next."

11. Specify a static path parameter.

    In this tutorial, we'll assign the name "GetSalesTasks."

12. Click "Next."

13. Skip the "Query Parameters" dialog step and click "Next."

    This takes you to the "Filter and Sort" dialog step.

    Filter by "Sales" team

    In the "Filter" section, we specify that only tasks from the "Sales" team should be displayed.

14. Click the " " icon.

    The "Filter Expression Properties dialogg box appears.

15. Select the "Custom" option and enter the string "Sales" in the "String" input field.

    

16. Click "OK."

    You will return to the "Filter and Sort" dialog step.

    Sort Return Values

    Finally, the sorting of the return values needs to be specified. These should be sorted by the project to which they belong.

17. First, clear the default sort order by "Title <string>." (This would correspond to sorting by the title of the assignment.)

18. Click the " " icon.

19. Select "Task" > "Project - (REF-PK) ID <string>."

20. Click "Finish."

21. Click the " " icon (Publish the application in full).

Next Steps

Now proceed as usual. Grant permissions for the API endpoint, generate an API key or activate an existing API key for the API endpoint, create the Swagger documentation, and import it into Postman.

After the request is executed, the following JSON file is returned.

Identify the tasks of any team

Requirement

You want to get an overview of the tasks of any team. To do this, you would like to enter the name of the respective team in an input field or select it from a drop-down list, and then receive the following information in return:

• Team Name

• Project Title

• Titles of the Assignments

• Task Status

Procedure

Most of the steps in this requirement correspond to the steps involved in identifying tasks for a specific team. The main change is that, instead of a static query, a dynamic query is created that allows the user to enter or select the team for which they want to retrieve the tasks. This is configured in the "Query Parameters" dialog step. At the same time, filtering for the string "Sales" in the "Filter and Sort" dialog step is no longer applied.

Step-by-Step

To get an overview of all the tasks for any team, follow these steps:

1. Create a new endpoint and give it a descriptive name.

2. Now follow the steps described in "Identifying the Tasks of a Specific Team."

• Select the data fields.

• Rename the data fields.

• Specify a static path parameter.

  In this tutorial, we'll give it the name "GetTasksPerTeam."

3. Click "Next."

   You will be taken to the "Query Parameters" dialog step.

4. Click the " " icon.

5. In the "Name" input field, enter the name for the query parameter "teamTitle".

   The name of the query parameter will be available to you later in the "Filter and Sort" dialog step.

6. In the "Data Type" drop-down menu, select "STRING."

7. Click the " " icon next to the "Fallback" input field.

   

8. Select the "Static Value" option.

9. In the "Static Value" input field, enter the text "Sales."

   If no value is specified for the "teamTitle" (query) parameter when the request is executed later, the tasks for the "Sales" team will be retrieved by default.

10. Click "OK."

    The dialog step now appears as follows:

    

    The query parameter is displayed in the left pane. The data field to which the query parameter refers is not yet displayed, as it has not yet been specified. This is done in the next dialog step, "Filter and Sort," in the "Filter" section.

11. Click "Next."

    This takes you to the "Filter and Sort" dialog step.

    Filter by "Sales" team

    In the "Filter" section, we specify that only tasks from the "Sales" team should be displayed.

12. Click the " " icon.

    The "Filter Expression Properties" dialog box appears.

13. Select the "Binding" option.

    Click the " " icon

    

    This will take you to the "Binding Properties" dialog box.

14. Select the "Parameters (Application API)" option on the left.

15. On the right, below "Parameters (Application API)," select the "teamTitle" parameter.

    

16. Please confirm your information.

    You will return to the "Filter and Sort" dialog step.

    Data Field for Query Parameters

    If you click the "Back" button, you will return to the "Query Parameters" dialog step. The data field for the query parameter is now displayed there.

    

    Sort Return Values

    Finally, the sorting of the return values needs to be specified. In this case as well, these should be sorted by the project to which they belong.

17. First, clear the default sort order by "Title <string>." (This would correspond to sorting by the title of the assignment.)

18. Click the " " icon.

19. Select "Task" > "Project - (REF-PK) ID <string>."

20. Click "Finish."

21. Click the " " icon (Publish the application in full).

Next Steps

Now proceed as usual. Grant permissions for the API endpoint, generate an API key or activate an existing API key for the API endpoint, create the Swagger documentation, and import it into Postman.

After executing the request, the following JSON file is returned for the "Marketing" team, for example.

More Information

• Create an API endpoint for an application

• Create Application API Endpoints

• Endpoint - Read Multiple Records