Creating an API endpoint for an application - Advanced

Tutorial content

This tutorial describes two slightly more advanced use cases for creating API endpoints. This is about restricting or filtering the values returned with a request.

In the first use case, this is still "static". This means that we specify a certain team from the task manager, for which all tasks, sorted by projects, are 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 manager. Subsequently, the tasks of this team, sorted by projects, are returned.

For the restrictions and selections described here, we use the filter dialog and the "Query parameters" dialog step.

Preparatory tasks

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

For the Advanced Tutorial, the same preparatory activities must be carried out as for the tutorialCreate an API endpoint for an application" :

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

   • https://www.postman.com/

   • https://web.postman.co

 

Identify the tasks of a particular team

Requirement

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

• Team title

• Project title

• Title of tasks

• Status of tasks

The "Task" data group contains all the data fields required to retrieve the desired information. The "Title" data field belongs more directly to the "Task" data group. It contains the task title. The other data fields are referenced in the "Task" data group from the "Team", "Project" and "Status" data groups.

Procedure

Step-by-step guide

To get an overview of all the tasks of the "Sales" team, proceed as follows:

1. Create a new endpoint and assign a descriptive name for it.

2. Click on "Data group endpoint".

3. Click on "Next".

   The "Data group selection" dialog step appears.

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

5. In the "Application" selection field, select the value "(current application)".

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

7. Click on the icon.

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

Select data fields

9. Select the following data fields in the "Add data fields" dialog box:

   • Title <string>

   • Project - Title <string>

   • Status - Title <string>

   • Team - Title <string>

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

   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 display these in the Intrexx ExpertExpert mode). To display the fields, select the data group. Right click on it. Select "Show data fields" in the context menu. Select the referenced data field. Right click on it. Select "Properties" in the context menu. Switch to the "Expert" tab.

   

   Add data fields one after the other

   You can add the data fields one by one and rename the newly added field each time.

10. Click on "Next".

11. Assign a static path parameter.

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

12. Click on "Next".

13. Skip the "Query parameters" dialog step and click on "Next".

    The "Filter and sort" dialog step appears.

    Filter on team "Sales"

    In the "Filter" area, we specify that only the tasks of the "Sales" team are queried.

14. Click on the icon.

    The "Filter expression properties" dialog box is displayed.

15. Select the "User-defined" option and enter the character string "Sales" in the "Character string" input field.

    

16. Click on "OK".

    You return to the "Filter and sort" dialog step.

    Sort return values

    Finally, the sorting of the return values is to be defined. These should be sorted by the project they belong to.

17. First delete the default sorting by "Title <string>". (This would correspond to sorting by task title.)

18. Click on the icon.

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

20. Click on "Finish".

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

Next steps

Now proceed as usual. Assign the rights to the API endpoint, create 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.

Determine the tasks of any team

Requirement

You want to get an overview of the tasks for any team. To do this, you want to enter the title of the respective team in an input field or select it from a selection field and then have the following information returned:

• Team title

• Project title

• Title of tasks

• Status of tasks

Procedure

Most of the steps in this requirement are the same as the steps in determining the tasks for a particular team. The key difference is that you create a dynamic request instead of a static request, where the user can enter or select the team for which they want to determine the tasks. This is set up in the "Query parameters" dialog step. At the same time, filtering on the character string "Sales" in the "Filter and sort" dialog step is no longer necessary.

Step-by-step guide

To get an overview of all tasks of any team, proceed as follows:

1. Create a new endpoint and assign a descriptive name for it.

2. Now proceed as for "Determine tasks of a specific team".

• Select the data fields.

• Rename the data fields.

• Assign a static path parameter.

  In this tutorial, we assign the name "GetTasksPerTeam".

3. Click on "Next".

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

4. Click on the icon.

5. Enter the name for the query parameter "teamTitle" in the "Name" input field.

   The name of the query parameter is available later in the "Filter and sort" dialog step.

6. Select the value "STRING" in the "Data type" selection field.

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

   

8. Select the "Static value" option.

9. Enter the text "Sales" in the "Static value" input field.

   If no value is subsequently entered for the (query) parameter "teamTitle" when the request is executed, the tasks of the "Sales" team are determined by default.

10. Click on "OK".

    The dialog step is now as follows:

    

    The left pane displays the query parameter. The data field to which the query parameter refers is not yet displayed, since this has not yet been determined. This is done in the next dialog step "Filter and sort" in the "Filter" area.

11. Click on "Next".

    The "Filter and sort" dialog step appears.

    Filter on team "Sales"

    In the "Filter" area, we specify that only the tasks of the "Sales" team are queried.

12. Click on the icon.

    The "Filter expression properties" dialog box is displayed.

13. Select the "Binding" option.

    Click on the icon

    

    The "Binding properties" dialog box appears.

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

15. Select the "teamTitle" parameter on the right under "Parameters (Application API)".

    

16. Confirm the information you have entered.

    You return to the "Filter and sort" dialog step.

    Display data field for query parameters

    If you click on 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 is to be defined. In this case, they should also be sorted according to the project they belong to.

17. First delete the default sorting by "Title <string>". (This would correspond to sorting by task title.)

18. Click on the icon.

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

20. Click on "Finish".

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

Next steps

Now proceed as usual. Assign the rights to the API endpoint, create an API key or activate an existing API key for the API endpoint, create the Swagger documentation and import it into Postman.

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

More information

• Create an API endpoint for an application

• Creating Application API endpoints

• Endpoint - Read multiple data records