REST API call Procedure step enhancements
The "REST API call" Procedure step has been improved with various new features that further expand its flexibility, allowing Makers to better manage integrations with third-party applications and manipulate incoming and outgoing data more effectively.
The new options and properties mainly apply to the "Main settings and parameters" configurations, the "Output configuration" and the Procedure Debugger.
Pagination parameter
A new parameter can be added to the step configuration to handle pagination of returned data. Pagination is essential when dealing with very large data-sets, as it divides returned data into smaller chunks to serve the user and not overload network traffic.
To add pagination parameters to the request, click on the "PAGINATION" button to add a new row in the table. The new row includes the "Parameter name" field, three new fields specific to pagination in the "Value column, and the "Type" field.
The three new fields are the following:
- Value (required). Depending on the method supported by the endpoint you are calling, this field tells the server the number of items that should be skipped, the first page to consider, or the first record to consider
- Increment (required). Depending on the method supported by the endpoint you are calling, this field tells the server the number of items that should be returned, the increment of the page number based on the value of the previous response, or the increment of the record number based on the value of the previous response
- Stop after (optional). This field lets you define the maximum value for the parameter. When that limit is reached, the paginated calls will stop
All three fields support only integers and Data pickers that are evaluated at runtime: if the result is not an integer, the step will fail.
The "stop after" field can also be left blank.
The paginated calls will stop as soon as the "stop after" value is reached or the remote servers send a response with no records or an error response. If multiple "stop after" values have been set in multiple rows of the parameters table, the paginated calls will stop as soon as the first "stop after" value is reached.
In the case of the "Show dialog" output configuration, paginated calls will stop when the maximum number of rows that can be displayed is reached.
The received data chunks are always merged together according to the output configuration setting.
In the "TEST CALL" dialog, only the first chunk of data will be considered and displayed.
Examples
1) Method: page number
Configuration:
Requests:
https://fakeapi.com/data?Page=1&PerPage=80
https://fakeapi.com/data?Page=2&PerPage=80
etc.
2) Method: limit/offset
Configuration:
Requests:
https://fakeapi.com/data?Page=1
https://fakeapi.com/data?Page=81
etc.
3) Method: start/end
Configuration:
Requests:
https://fakeapi.com/data?Start=1&End=80
https://fakeapi.com/data?Start=81&End=160
etc.
Support of the @Selection_Ex substitution formula and the Data Picker in the "Value" field
The "Value" field in each parameter row now supports the @Selection_Ex substitution formula to pass the currently active Selection to the API request as a parameter value, to overcome limitations of the @[entityname] and @selection formulas in terms of format customization.
As with every other Procedure step, the range or scope of execution on the Entities is inherited from the Select and the Pager selections of the Screen from which the Procedure is launched. These inherited selections will be combined with the contextual Procedure selections.
Compared to the use of the @Selection_Ex in Layouts and Screens, the implementation of this formula in the REST API call step differs in the following points:
- The "Layout" and "Block" parameters are not supported
- The Entity parameter is required
- The result of an @Selection_Ex resolved in the REST API call step context is similar to what happens in a Screen with the "ShowActive" parameter set to "True" (in this step, this parameter is not supported)
- The "Limit", "Display", and "Interval" parameters are supported
- The new "Separator" parameter can be used to define a custom separator string for the resulting Entity member list. If it is not defined, the comma separator will be used.
Example:
- If all members are selected, the output list will include all members separated by the separator string
- If no members are selected, the output list will be an empty string
Example
If the contextual selection of a Procedure includes the "2021", "2022", and "2023" members of the Entity "Year", you could configure the @Selection_Ex as in the image below:
With this configuration, the API request would look like this:
https://fakeapi.com/data?year=2021,2022,2023
The "Value" field in each parameter row now also supports the Data Picker function to extract data from a Cube or a Temporary Cube with a custom selection (optional) and pass those values to the API request as a parameter value.
The Data Picker is evaluated at runtime considering the context of the Procedure for the active selection. If a custom selection in specified in the Data Picker syntax, it will be considered for the evaluation at runtime, ignoring the context-inherited selection for the referenced relationship tree.
Compared to the use of the Data Picker in Layouts and Screens, the implementation of this function in the REST API call step differs in the following points:
- No formulas are supported in the Data Picker syntax
- You cannot specify a Data model other than the one where the Procedure resides
- If the referenced Cube cannot be found, the step will fail
If the Cube name, Entity name, of member code include a system-reserved character and an error is returned, enclose the string in double quotes to solve the parsing problem
Support of Substitution formulas and Data Pickers in the "API path" and "Parameter name" fields
The "API path" and "Parameter name" fields now support Substitution Formulas and Data Pickers, thus allowing more flexibility in the configuration of the step.
In the "API path" you can enter Substitution Formulas and Data Pickers as a part of the URL path. These elements are evaluated at runtime.
Example:
You can also enter Substitution Formulas and Data Pickers in the "Parameter name" field of each parameter in the "Parameters" table. These elements are also evaluated at runtime.
Example:
Output configuration
New "Show dialog" option
If the request is successful and the response includes a payload (data received) that you want to display in Board, select the new "Show dialog" option. This new option works much like the drill-through and will show the data received from the remote server in a dialog.
The configuration of this output option is similar to the configuration of the "Save returned data" option and can be accessed by clicking the "TEST CALL" button: at the last step of the configuration process, the Maker will be presented with a preview (first 100 rows) of the extracted data.
The ”SAVE SAMPLE” button allows to save the data returned (first 100 rows of the actual data) to a .csv file.
In Play mode, the dialog will display the full set of returned data. The user will be able to download the data displayed in the dialog by clicking the "EXPORT TO EXCEL" button at the bottom of the table.
CONFIGURE/TEST CALL dialog enhancements
The CONFIGURE/TEST CALL dialog that opens when you click on the corresponding button under "Output configuration" (If the "Save returned data" or the "Ignore returned data" option is selected) has been improved with more information about the API request. This is particularly useful for debugging purposes.
After submitting the API request in the dialog, the tabbed menu in the dialog now includes a new "REQUEST" item. Click on it to review all details about the API request that has been sent (URL, Headers and Body).
Procedure Debugger and logging enhancements
The Procedure Debugger tool has been enhanced with specific features to better support debugging of Procedures that include "REST API call" steps.
In detail, if you add a breakpoint next to a "REST API call" step, in the Watch window you will find a new tab specific to this step, named "REST API": from there you can click the "TEST CALL" button to access more details about the request, in the current context of the Procedure (including Selections, Temporary Cubes and more).
In the case of paginated calls, only the first request will be sent from the "TEST CALL" dialog. Subsequent pages can be reached by manually adding the corresponding paging parameter values to the request.
All dynamic elements (Layout definitions, Substitution formulas, Data Pickers) are evaluated in the context of the Procedure before sending the test call from the "TEST CALL" dialog.
In the Diagnostic log launched in the 2021 Winter release we have included more REST API call step configuration details in case of errors: at verbosity level "Information", when the remote server returns an error, the corresponding log entry will also include the URL of the request sent, the method, the Headers, and the Body (if applicable).