Actions
A Web API definition can include multiple Actions, each one representing a different request to a specific endpoint using the required HTTP method. All configured actions for an API display in the navigation tree and are listed in the main screen when the Actions node is selected.
Click Add Action to create a new action for an API definition and configure the associated parameters.
Add a name and description and apply action specific settings.
Name
A unique name for the action. The name is used when selecting business objects for actions in Object and Process Studio.
Description
An optional description to provide more information about the action.
Enabled
Actions must be enabled to be available for selection in objects and processes.
Enable Request Data Output Parameter
When selected, creates a Request Data output for an action in Object Studio and Process Studio. When an action runs, the associated data item is populated with the API request data.
Disable sending of request
When this option is selected, the request data is generated but the request is not sent to the server. Use in conjunction with Enable Request Data Output Parameter to generate a request without contacting the server, providing a mechanism for debugging and evaluating requests.
These parameters are specific to the action and are used in combination with the common parameters as the inputs for an action in objects and processes. When enclosed in square brackets, parameter names are used dynamically to add their values to URLs, header values, and request bodies.
For further information, see Parameters.
Define the HTTP Request that will made to this API Endpoint by selecting the required HTTP method and adding the URL path, body content, and headers.
Method
The HTTP method used for the request. The drop-down contains the standard HTTP methods but any request verbs can be entered into the free-text field. Validation is performed on the field to prevent the input of non-allowed characters.
URL Path
The URL path particular to the action that defines the specific request when used with the base URL. The URL path can be parametrized using common and request-specific parameters, enclosed in square brackets.
For example, the base URL is:
http://staff.database.com
The URL Path is:
/api/[version]/employee/[id]
When the parameters are expanded and added to the base URL, a request is made to this address:
http://staff.database.com/api/v1/employee/26855
Body
Configure the content to be sent with the HTTP request using one of the following content types:
- None – The request does not include body content. This is usual for actions that retrieve information, such as those using the GET method.
- Template – Send text-based body content such JSON or XML. Parameters can be used to add data to the request body.
- Single File – Send files as part of the API request. The API definition specifies an input parameter that is used to reference a file from a data stage in a process.
- Multiple Files – Send multiple files as part of the API request. The API definition specifies an input parameter that is used to reference files from a collection stage in a process.
- Custom Code – For complex scenarios the request body can be generated using code. Where required, this can incorporate code from the Common Code area of the API definition.
Headers (action-specific)
Add a name and value for each header specific to this action. The headers used in a request are a combination of the common headers in the API definition and the headers set at action level. If an action-specific header has the same name as a common header, the value of the action specific is used in any requests.
For further information, see Headers.
Transform the HTTP response using JSON Path or custom code to extract the required data. The data can be stored in data items, making it easier to use in other stages of an object or process. Custom code can be used to configure more complex responses, for example, performing calculations on the response data.
The response output is defined using the following fields:
- Parameter – The name of the output parameter created to store the data specified.
- Data Type – The data type of the output parameter.
- Method – The method can be either JSONPath or Custom Code. If using Custom Code, the outputs are ref parameters that need to be assigned.
- JSON Path – If using JSONPath, the expression needed to extract specific elements of the JSON into output parameters. These output parameters have a specified Blue Prism data type, and the object found using the JSON Path will be converted to that data type.
- For further information about configuring responses, see Extracting response data with JSON Path.