REST Web Services package

Use the actions in the REST Web Services package as methods (DELETE, GET, PATCH, POST, or PUT) to send requests to and receive responses from an API.

Working with REST Web Services actions

Provide the following information to send a REST request and receive a response. Not all parameters are required for all methods.

Enter the URI: A unique address for an API resource.

Proxy configuration: To set the proxy, select the System or Custom tab from Proxy configuration.


Option	Description
System	System proxy is the proxy configured on the bot runner machine where the bot is running. If this option is selected, the Bot Agent uses the system proxy.
Custom	This option allows you to configure custom proxy settings within the actions of REST Web Services. For example, if a REST API is required to be routed through a different proxy other than the system proxy, you can select the Custom option and provide proxy details within the REST actions. Provide the following details: Host: The host name or IP address of the proxy Port: The port number of the proxy Username (Optional): The username used for the proxy authentication Password (Optional): The password used for the proxy authentication Note: If the proxy to be configured is authenticated proxy, then you must provide authentication credentials in the Username and Password fields. For Host, Port, Username, and Password fields, choose from Credential, Variable, or Insecure string tab : Credential: Use a value available in the credential vault. Variable: Use a variable that stores a credential value in a user-defined variable. Insecure string: Manually specify the value that you want to use.

Authentication Mode: There are three supported authentication modes:
- No Authentication: Use this option to access the endpoints that does not require authentication to access their servers.
- Control Room user token: The REST Web Services actions uses the token generated while you logged in the Control Room to access the endpoints.
- Basic: Basic is the simplest way to authenticate users. When you select this option, you will enter the username and password. This technique uses a header called Authorization, with a base64 encoded representation of the username and password entered.
- Logged-in AD User: Active Directory (AD) users that are authorized to access the related API are authenticated through AD. No credentials are required in the request.
- Windows NT LAN Manager (NTLM) Authentication (AD User): A challenge/response authentication method that allows clients to provide their user name and password as encrypted credentials or plain text. We recommend that you use credentials that are stored in the Automation Anywhere Credential Vault.
- OAuth2 - Control Room managed: When you integrate OAuth with the Control Room, you can centrally manage and securely store tokens that are used to authenticate with third-party providers. You must configure the web service and make note of the authentication details (such as such as client ID, client secret, authorization URL, and so on) to use the OAuth connection in the Control Room. For more details, see Configure OAuth connections in Control Room
  The following video shows how to use OAuth connection in REST Web Services:
Header: Not all methods require a header. Headers represent the metadata associated with the request.
Content type: When a header contains a content type, it defines the content negotiation between the client and the server. REST Web Services actions support the following content types:
- application/x-www-form-urlencoded: Encode the parameters in the URL.
- JSON (application/json): Enter a JSON request body.
- XML (application/xml): Enter an XML request body.
- Text (text/plain)
- XML (text/xml)
- HTML (text/html)
- multipart/form-data:
  - Send binary data, in most cases for uploading files to the server. It is used in cases where you are sending multiple parts in a single request, typically including text data (like form fields) and potentially a file upload. You can also use a FileStream variable. See below for more information.
  - FileStream: The FileStream can be read after assigning it to a variable. For instance, you can read a FileStream assigned to a variable in an OneDrive location. For more information, see Assign file action.
- Binary: Use Binary to send raw files such as images, videos, and audio files. When you select Binary you will be able to upload a binary file (as a variable, Control Room file or Desktop file).
- Custom
  Custom: Add custom content that does not fall under the standard content type. For example, when you are migrating from v.11.x to Automation 360, the following value does not fall under any of the standard content types: application/vnd.whispir.message-v1+json
Add substitution: Allows you to enter variables in the REST request body. A variable is a symbolic representation of data, and it enables you to access a value without having to enter it manually wherever you need it. For example, consider the following REST body request:
```
{
   "name":"{{name}}",
   "email":"{{email}}",
   "status":"Active"
}
```
In the above request body, you can replace the variables enclosed within double braces by clicking Add substitution and adding the required values.
Advanced options:
- Capture failure response: Select the check box to capture the failure response except for the Success/Ok response. The failure response details are captured in the response body.
- Allow insecure connection when using https: Select the check box to allow insecure connection when using https.
- Accept Cookies: Select the check box to automatically capture session cookies from server responses.
  - Capture: When enabled, the feature captures session cookies included in server responses.
  - Secure Storage: Captured cookies are encrypted within process memory, ensuring they are never permanently stored and are inaccessible outside your automation session.
  - Reuse: Cookies are automatically included in subsequent REST calls, eliminating manual cookie handling and improving automation reliability.
  - Multiple Cookie Handling: The feature seamlessly handles multiple cookies returned by the server, ensuring all necessary authentication credentials are included.
  - Destruction: Captured cookies are automatically destroyed when the automation session ends or the bot finishes execution, ensuring data security and privacy.
  Note: The captured cookies are specific to the domain they originate from and will not be automatically used for subsequent REST calls made to different domains. This means cookies captured from domainA.com will not be utilized for requests to domainB.com.
- Download file: (Only available with the Get method) Select this check box to download the file to a specific location. The URI must return/download a file. Enter the desired folder path and filename with extension. Ensure you use the correct file extension. For example: C:/Users/Downloads/image01.jpg
  Tip: Mark the Overwrite file if already exists option to overwrite a file of the same name that already exists in the folder you are saving the file to.
  Error handling:
  
  Invalid URI:
  
  If the provided URI is incorrect, an error message will be displayed.
  
  File not found:
  
  If the API response is empty because the file does not exist at the specified location, an error message will be displayed.
  
  Insufficient permissions:
  
  If you do not have write permissions for the download location, an error message will be displayed.
  
  File extension mismatch:
  
  If the file extension does not match the expected type, an error message will be displayed.
Wait for action to complete: You can set a time-out value when you send a REST request and receive a response. When performing actions such as POST, PUT, DELETE, PATCH, and GET, in the Wait for action to complete field, you can specify the wait time (in milliseconds). By default, the wait time is 60000 milliseconds.
Output variable: The response output is captured in a dictionary variable. A dictionary variable is a key-value pair. Use the response header name as key to return the header value, or "Body" as the key to return the response body.
Note: The response key with its value is available in the dictionary variable to display the response status of the REST API.
To obtain a list of the header names for the API resource, perform these steps:
1. Insert a Loop action after the REST Web Services action.
2. Select the For each key in the dictionary iterator.
3. In the Dictionary variable field, select the variable that holds the REST Web Services action output.
4. Assign the value of each key to $prompt-assignment$ .
5. Insert a Log To File action.
6. Provide the file path to a text file to hold the list of header names.
7. Insert $prompt-assignment$ in the Enter text to log field.
8. Select the Overwrite existing file option.
9. Click Save.
  When you run the bot, it prints the header names from the API resource to the selected file.

Passing values securely

You can securely pass values from the Credential Vault to the web service by specifying the locker, credential, and attribute in the following supported action fields:

URI
Custom headers
Body: For the application/x-www-form-urlencoded content type, click Add parameter to select the value from the Credential Vault.
For all other content types, select the Select credential as parameters option and click Pick.

Actions in the REST Web Services package


Action	Description
Delete method	Removes the resource that is identified by the URI.
Get method	Retrieves information identified by parameters included in the URI. There is no Content type for the GET method because all the parameters are passed as part of the URI. Limitations and characteristics of the GET method include the following: URI length is limited to 2048 characters. All parameters are passed in the URI. The GET method exposes data that is in the URI, making it less secure than the POST method. GET does not change any data, making it safe for all users regardless of authorization. See Using the Get method.
Patch method	Modifies the resource that is identified by the URI.
Post method	Creates a new resource in the URI. Parameters are passed in request body. There is no limit on length for a request body. See Using the Post method.
Put method	Updates or replaces a resource based on parameters passed in the URI or body. See Using the Put method.

Proxy support

If your device is configured with a proxy, all outbound requests from this package are routed through the proxy server. See Connect Bot Agent to a device with a proxy.