Server API Tool
Server API Tool
Use the Server API tool to interact with the Server API (v1, v2, and v3) without the need to write a complex workflow. To learn about Server API access, authentication, endpoints, parameters, and versions, go to the Server API Overview page.
Tip
This tool is not automatically installed with Alteryx Designer. To use this tool, download it from the Alteryx Marketplace.
Requirements and Compatibility Notes
The Server API tool is compatible with Designer and Server version 2021.4 and newer. Note that certain capabilities of the tool can be limited based on your Server version.
Compatible with both Alteryx Multi-threaded Processing (AMP) and the original Engine.
Required Package Installation
The Server API tool requires that you have these packages installed on your machine:
oauthlibrequests_oauthlib
If you don’t have these packages installed…
Add the Server API tool to your workflow canvas and run the workflow. The tool generates an error to alert you of any missing packages.
Navigate to the workflow Results window and select the All tab (or Files tab to narrow the list of items).
Locate and select the message that reads: “Run this linked workflow as Admin to install missing packages.” This opens a new workflow with a Python tool that is preconfigured to install the necessary packages. Run the workflow to perform the installation. Note that you need to run this installation workflow as an Administrator.
Alternatively, you can replicate the above and install the packages via the Python tool. Go to Additional Package Installation to learn how to install packages.
Tool Components
The Server API tool has 6 anchors:
Input Anchors (both are optional):
A (Authorization) input anchor: If you choose to use values from fields in the tool configuration, use this anchor to supply your authorization information. Select the field that contains your API base URL and another field that contains your authorization information (typically this is the Authorization field from the A output of an upstream Server API tool). Note that the authorization information is a combination of the Bearer prefix and access_token that oAuth2.0 generates when you initially authenticate. Go to Server API Configuration and Authorization for more information.
D (Data) input anchor: If you choose to use values from fields in the tool configuration, use this anchor to supply parameters for your endpoint. Note that certain Endpoints have required parameters.
Output Anchors:
A (authToken) output anchor: This anchor outputs your authentication information so that it’s readily available should you want to make multiple calls. Connect this output anchor to the A input anchor of another Server API tool to seamlessly reauthenticate another API call downstream.
S (Success) output anchor: This anchor outputs any API calls with a response code of 200. We parse the API responses one level down* and output the fields here. If we can’t parse a response, the Extracted output field contains a message with the reason, and we provide the raw data in the DownloadData and BinaryData output fields.
F (Fail) output anchor: This anchor outputs any API calls that don’t receive a response code of 200.
L (Logs) output anchor: This anchor outputs the log information that results from your API call.
*Example Response
This response is simplified for the sake of this example. The raw JSON example displays a typical JSON response, followed by an example of the same response via the Server API tool.
Raw JSON Example Response
[
{
"id": "12345",
"dateCreated": "2023-05-02T16:50:05.829Z",
"runCount": 0,
"versions": [
{
"versionId": "67890",
"versionNumber": 1,
"dateCreated": "2023-05-02T16:50:05.829Z",
"details": {
"isAmp": false,
"fileName": "test.yxmd"
}
}
]
},
{
"id": "54321",
"dateCreated": "2023-05-03T10:50:48.681Z",
"runCount": 0,
"versions": [
{
"versionId": "09876",
"versionNumber": 1,
"dateCreated": "2023-05-03T10:50:48.681Z",
"details": {
"isAmp": false,
"fileName": "test2.yxmd"
}
}
]
}
]
Example Parsed Response via Server API Tool
The same response is formatted as follows via the Server API tool. Note that the versions item is consolidated into one column/field in the Server API tool response.
id | dateCreated | runCount | versions |
|---|---|---|---|
12345 | 2023-05-02T16:50:05.829Z | 0 | [{'versionId': '67890', 'versionNumber': 1, 'dateCreated': '2023-05-02T16:50:05.829Z', 'details': {'isAmp': False, 'fileName': 'test.yxmd'}}] |
54321 | 2023-05-03T10:50:48.681Z | 0 | [{'versionId': '09876', 'versionNumber': 1, 'dateCreated': '2023-05-03T10:50:48.681Z', 'details': {'isAmp': False, 'fileName': 'test2.yxmd'}}] |
Configure the Tool
Use the tool configuration window to configure any necessary fields to execute your API call.
Authentication
Use the Authentication section to provide the required authentication information. Go to API Keys and API Access as well as Server API Configuration and Authorization for information.
Use values from fields: Off by default. Turn on this toggle to specify an incoming field that stores your base URL and authorization token (API Access Key and API Access Secret) information. Select the fields via the Select Base URL field and Select Authorization field dropdowns. If you use this option, we only use the first record that you provide as the base URL and authentication token.
You can also supply your authentication information directly via the tool configuration window. Note that these fields are hidden if you turn on the above Use values from fields toggle.
Base URL: Provide the base URL for your Server API. You can configure this via Server UI Configuration.
API Key: Enter your API key.
API Secret: Enter your API Secret.
API Configuration
Use the API Configuration section to select your method, choose an endpoint, and provide parameters for your API call.
Choose Method: Use this dropdown to select your API method. Choose from…
GET: The GET method lets you read or view a resource. For example, the GET method on a users endpoint allows you to read or view a list of users.
POST: The POST method lets you create a resource. For example, the POST method on a users endpoint allows you to create a new user.
PUT: The PUT method lets you update a resource. Specifically, the PUT method replaces the existing resource. For example, the PUT method on a users endpoint allows you to update by replacing existing user details with the user information you provide.
DELETE: The DELETE method lets you delete a resource. For example, the DELETE method on a users endpoint allows you to delete an existing user. When you select the DELETE method, the Confirm DELETE Method switch appears. You must enable this switch to successfully execute a deletion.
Endpoint: Use this dropdown to select your endpoint. Options vary depending on the method you select. To learn more about Server API Endpoints and Parameters, go to API Endpoints and Parameters, Access Server API V3, and Server V3 API Objects.
Use incoming fields for Parameters*: Off by default. Turn on this toggle to specify incoming fields to use as parameters. Next, use the available dropdowns to specify the field that contains the parameter information.
Enter parameter values*: If you choose not to use incoming fields for your parameters, you can enter parameters directly via the provided fields.
Endpoint Parameters
Note that the available parameters depend on the Endpoint. Additionally, some endpoints have required parameters, while others don’t. To learn more about Server API Endpoints and Parameters, go to API Endpoints and Parameters, Access Server API V3, and Server V3 API Objects.
Payload: If you choose to enter the payload manually, you can enter it here directly in JSON format. Alternatively, use the above Use incoming fields for Parameters toggle to specify the incoming field that contains the payload.
Schema Example: If applicable, the Schema Example is populated with a correct structure for the API payload. You can select the Use schema in Payload button to copy the generic text into the payload tab and modify it.