Engine Works
Under the hood of Alteryx: tips, tricks and how-tos.
Introducing Alteryx Server v3 API endpoints
With the release of Alteryx Server v21.4, there are a series of new Gallery API capabilities.
Purpose of the Updates
If you had used the v1 and v2 endpoints, you will have noticed that they are very similar to one another. V1 and v2 endpoints serve three main use cases:
- Workflow Execution
- Content Oversight
- Workflow Migration
With the addition of the v3 endpoints, you'll notice a much larger set of endpoints, and a focus on administration of Gallery content, including updating, deleting, and creating most types of assets. This ability to programmatically perform CRUD operations on most types of assets allows for a wide variety of administrative use cases, from data-driven user management, to integrated scheduling, to bulk data connection management. Accessing these endpoints is available to Admins (Curator role).
Alteryx Server is moving away from a reliance on Studios for workflow administration to a focus on authorization via Collections. These new v3 endpoints provide new options for this migration, as well as other migration scenarios.
What's New?
One significant change between v1, v2, and v3 is in the authorization mechanism.
Both v1 and v2 endpoints use the same OAuth1.0a method to sign every single request, and therefore don't reuse a token or signature when sending multiple requests. This OAuth1.0a method relies on "signing" a request by generating a string which contains most of the details about the request, including the base URL, serialized parameters, a random nonce, timestamp, and API Access Secret. The resulting string is hashed with HMAC-SHA1, and that "signature" is sent along as an additional parameter with the actual request, minus the API Access Secret. When the Server successfully rebuilds the signature from the provided values plus the local API Access Secret, then Server knows the client had the correct secret and that the request had not been tampered with.
The new v3 endpoints are authorized for use by providing a valid "bearer token" with requests. To generate the token, you'll need two values- Client ID (aka "API Access Key") and Client Secret (aka "API Access Secret")- which get concatenated together separated by a colon, Base64 encoded, prepended with "Basic " and then posted to the /webapi/oauth2/token endpoint in an "Authorization" header. An "access token" is provided in response, and that token can then be used as the Authorization header value (prepended with "Bearer ") in subsequent calls to any of the other v3 endpoints. The token lives for a total, non-configurable time of one hour, after which time a new token will need to be generated.
* OAuth 2.0 available with v1 and v2 when using new “/webapi/” path instead of original “/api/” path
Use Cases
Because these endpoints are focused on content administration, their availability opens up a wide range of possible uses, including:
- Migrating content from one Server environment to another
- Automated deployment of workflows from a centralized version control repository
- On SAML-configured Server's, more granular definition and authorization control
Note that not all content can be directly migrated from environment to another as some concepts such as Gallery shared Data Connections are designed to be environment-specific.
Getting Started with v3 API Endpoints
Alteryx Server comes with the interactive documentation for the API by default. In v21.4, the v3 Swagger documentation will reside at [WEB API ADDRESS]/swagger/ui/index]. This will allow you to see the required parameters for each endpoint, actually issue requests, and see the responses. Note that the base API address is configurable via System Settings with Server v21.4.
Introducing the v3 API Macro Pack
There are obviously many possible ways to call API endpoints, including Alteryx workflows. We've built a macro pack to easily interact with these new v3 endpoints. Having Alteryx tooling available for Server API interactions allows for fast and flexible integrations. The pack consists of five macros:
Installing the v3 API Macro Pack
The YXI installer for the Macro Pack is included below. The Macro Pack uses the new v3 API endpoints, which are available starting in Alteryx Server 2021.4. To use the macros, you will also need to be running Alteryx Designer 2021.4.
When installing the Macro Pack using the YXI, you can install it for the executing user, or for all users on the machine (requires Admin privileges). When installing the Macro Pack in an Alteryx Server environment, you must install the YXI for all users by running Alteryx Designer as an administrator.
Using the v3 API Macro Pack
After installing the macros on a machine with Alteryx Designer, a new tool folder should appear in your Designer called “Server v3 API". Before using the macros, consult the interactive Swagger documentation to understand the parameters that the desired endpoint requires or accepts. The macros allow you to choose an endpoint via the "Action" tab, and that selection then influences what fields are accepted/required for successful execution. For example, the endpoint CREATE /v3/collections/ requires a field called "contract" as a JSON object, so a field called contract with the properly formatted JSON object must be fed to the macro input.
The macros accepting inputs all require a unique "RecordID" field be included with each record, and can easily be generated with the Record ID tool. The macros accepting inputs also expect three fields which are generated by the AUTHENTICATE macro: "baseURL", "Authorization Token", and "Base64 Key+Secret", all of which should map automatically from the output of the AUTHENTICATE macro. If you intend to send multiple records into a given macro for multiple API calls, group by the unique "RecordID" field in the "Group By" tab. Lastly, you'll note that each of the four action macros provide success and failure outputs. Receiving failure records should allow you to perform validation and exception handling and/or reporting.
A simple process to create a new Collection would look like this:
These macros are designed for use with Alteryx Server v3 Gallery API endpoints and validated on Server version 21.4. The macro pack is provided as-is, without warranty. This macro pack is not a part of the base Alteryx Server product. Use of this macro should always be tested thoroughly in a non-Production environment to your satisfaction.
Frequently Asked Questions
- If I experience any issues with the V3 API macro pack, will Alteryx Support be able to assist me?
- The V3 API Macro pack is not an official Alteryx product offering and is provided as-is, without warranty, through the community as a field-developed solution. If you experience any issues, please leave a comment below.
- I already have an integration built on v1 and/or v2 endpoints. Will upgrade to v21.4 break those endpoints?
- No, v1 and v2 endpoints will continue to function as they have until they are deprecated, which is estimated to be two full releases after the v3 endpoints support all use cases served by v1 and v2.
- Can I build an application with a mix of v1 and new v3 endpoints?
- Yes, just note that the authentication and authorization frameworks are different, so you'll need to code your custom application accordingly.
- Can I configure the v3 bearer token timeout?
- No, this duration is currently not configurable, and lives for 3599 seconds (one hour).
- Can v3 results be paginated?
- V3 endpoints rely on a combination of filtering options and a verbosity parameter in place of the paging concept present in v1/v2
- Is sensitive data encrypted in the requests and responses?
- None of the three versions of the API offer a native encryption method. Encryption of traffic should be configured by installing a TLS certificate on the Server, which is considered standard practice.
- Can v3 endpoints perform all the same functions as v1 and v2 endpoints?
- As of Server v21.4, no. Some functions exist in more than one API version. V3 offers many new functions that are not available in v1 or v2. One notable function available in v1/v2 and not yet in v3 is the workflow execution function.
- How do I know what fields need to be fed into any of the macros?
- You select an endpoint within the "Action" tab of the given macro. The documentation for the endpoint, including required and optional fields, should be reviewed in the API Documentation that comes installed with the Server. Some fields for some endpoints are required to be JSON format, in which case the format specified in the documentation should be used.
