Community Spring Cleaning week is here! Join your fellow Maveryx in digging through your old posts and marking comments on them as solved. Learn more here!

Engine Works

Under the hood of Alteryx: tips, tricks and how-tos.
DanH
Moderator
Moderator

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. 

  

  

V1 API 

V2 API 

V3 API 

Transport 

http/https 

http/https 

http/https 

Authorization framework 

OAuth 1.0a, OAuth 2.0* 

OAuth 1.0a, OAuth 2.0* 

OAuth 2.0 

Session management 

stateless 

stateless 

1-hr bearer token 

Signed request 

yes 

yes 

no 

Focus 

Workflow Execution 

Oversight 

Content Administration 

Total Endpoints 

22 

8 

58 

 * 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:  

 

     DanH_0-1644017699992.png   GET Macro - used for reading records 

     DanH_1-1644017699993.png   POST Macro - used for updating records 

     DanH_2-1644017699994.png   CREATE Macro - used for adding new records 

     DanH_3-1644017699994.png   DELETE Macro - used for deleting or disabling records 

     DanH_4-1644017699995.png    AUTHENTICATE Macro - used to generate a token which can be reused in multiple requests for 3599 seconds from the time issued

 

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: 

DanH_5-1644017699996.png

 

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. 

 

Comments
patrick_digan
17 - Castor
17 - Castor

@DanH Great write-up, I'm excited to try out the new v3 API!

Thableaus
17 - Castor
17 - Castor

This is awesome. I'll see if I can find some time to test it

chvizda
8 - Asteroid

Hi all

I currently use the "Subscription" Endpoints of the "old" API capabilities.
Will they also migrated to the new V3 in near future ?

 

I saw only this message:

The V1/V2 API endpoints will be deprecated two releases after all use cases have been supported in the new V3 API.
We recommend writing all new scripts using the V3 API whenever possible.

 

Currently I'm writing new scripts, and I don't want to do it again in the near future.

 

Many thanks

 

Steffen 

Sebastiaandb
12 - Quasar

Like @chvizda we're currently using the "subscription" endpoint with the subscription key and secret to do post/get calls. However, within the new webapi interface i do find V1,V2 and V3 but it only let's me authenticate with my "API access key" and "API access secret", the subscription key and secret are not allowed and thereby i'm not able to post/get any workflow that i have in my private studio. 

 

Does anyone here have a clue were they integrated the api functionality for subscriptions? 

 

Thanks

 

Seb, 

JohnPelletier
Alteryx Alumni (Retired)

Hey folks, a few points to help clear things up on this thread:

 

  • V1, V2 and subscription API endpoints can all work with the user API key and secret now. No subscription key and secret are necessary going forward.
  • You should still be able to access any workflow from your private studio with your user key and secret. If you're having trouble with that, please open a support ticket and let's get that fixed for you.
  • V1, V2 and subscription API endpoints will continue to be around for a while. The message was intending to say that once we had fully replaced all of those endpoints with new V3 versions of them, we would later deprecate them and consolidate all APIs to just one version, but getting all of the V1, V2, and subscription API endpoints re-designed for V3 is not planned for at least a year.
JohnPelletier
Alteryx Alumni (Retired)

Also, a heads up for 2022.1 (our next release in May 2022).

 

We will be deprecating OAuth1 in Server v2022.1, so the migration to OAuth2 for your scripts is certainly coming to your future.

 

We hope this isn't a big deal, since it involves just an update to the base URL (typically from /gallery/api/ to /webapi/) and a change to the auth type (OAuth1 to OAuth2).  All the endpoints' parameters and responses should be identical, with the exception of the GET /workflows/id/package call, which will now return an actual file in the OAuth2 version where it used to return a binary BLOB.

 

If you find this extra challenging, please let us know how we can make it better and we'll do our best.

lepome
Alteryx Alumni (Retired)

@Sebastiaandb 
There is a known issue (original ID GCSE-440, also listed as TGAL-6414 for reference in future Release Notes) keeping Artisans and Viewers from using the v1 Subscription endpoints with OAuth2.  There are two workarounds until this is fixed in a future release.

  1. Use the older, OAuth1 interface a bit longer.
  2. Work with the Gallery Administrator/Curator to have them make those API calls or elevate you to Curator level if access must be OAuth2.
Sebastiaandb
12 - Quasar

Thanks @lepome ,

 

We notified our account manager 2 weeks ago about this (he's a great guy by the way ;-)).

Thanks for the workarounds but as OAuth1 will be depreciated in 2022.1 we will most likely just not upgrade until this is fixed. We are keen on changing all our back-end processes to the new OAuth2 standard (as we execute a lot via the api interface) but it needs to be usable by Artisans that are now utilizing the V1 subscription. 

Again, thanks for your reply, i appreciate it! 

 

Greetings,


Seb 

cAral
7 - Meteor

Thank you for sharing this @DanH!

 

Are you familiar with any additional documentation on the PUT /v3/workflows/{workflowID} endpoint? I've tried using it here in python to change a workflow owner (or even more simply, the workflow name) but keep running into a 400 error which I was able to replicate using these tools.

 

cAral_0-1651626269530.png

 

ITTeam
6 - Meteoroid

Any ideas on how to fix this issue with the V3 api? Can connect to the public URL but then receive this error, and the API options will not load: 

Can't read from server. It may not have the appropriate access-control-origin settings.

Is this an Alteryx Systems Settings problem or something that we'd need to get resolved on the LB side (we are running Gallery through an AWS ELB, it worked fine until we upgraded to the latest Alteryx version and are trying to test the V3 api). Thanks. 

levell_x_dunn
10 - Fireball

HI @DanH,

 

I was very excited to see all that was exposed on V3. Especially the ability to now help customers create a collection, add users and add workflows and schedules all through the API.

 

My team gets requests to add 30/40 workflows for these clients, then help other clients, and allowing to remove the manual work to now build into a few workflow templates looks really cool.

 

Unfortunately, I was testing this out as the Alteryx admin and came across a 403 error where I am being denied access to add a workflow or schedule to a collection.

I understand this not working for some people, as you don't want someone "stealing" a workflow but as admin support.. this baffles me 

 

Please see screenshot below

 

levell_x_dunn_1-1653162915252.png

 

DanH
Moderator
Moderator

@ITTeam  It sounds like it could be an issue with headers, though I'm not sure why a different version would behave differently in that regard. The HTTP headers provided by Server can be customized via  a config file at [INSTALL DRIVE]\Program Files\Alteryx\bin\server\config\alteryx.config. Within that file, there's a section httpHeaders , and any additions will be served with requests after restart.

ITTeam
6 - Meteoroid

Hi DanH! Thanks for your reply and for the location of the config file to alter the httpheaders. Will give this a shot. 

-Jonathan 

mchamlee
6 - Meteoroid

Trying to work with the V3 endpoints after upgrading to 2021.4 recently. Porting over custom Python classes/methods from V1, in particular the Publishing endpoint. Receiving 415 Unsupported Media Type with my V3 logic, and confirmed the same response when using the Alteryx provided Postman collection. Any tips/insight into troubleshooting this? I'm using a yxzp that I can publish fine with the V1 endpoint against 2021.4, so fairly certain it's not the yxzp itself.

JohnPelletier
Alteryx Alumni (Retired)

Is it one endpoint in particular that is causing this problem? What kind of response does your code currently expect?

mchamlee
6 - Meteoroid

@JohnPelletier First, apologies for the late reply. I don't appear to get community (or support) update emails anymore, started some months back.

 

This is just impacting one v3 endpoint so far, workflow publishing (/v3/workflows POST). The logic expects status 200, application/json response with the published Workflow id, but as I said this same issue also occurs in Postman which is generally uninterested in the code returned no matter what it is (left up to the user/tester to decide), it's 415 regardless of the tool/technology for me.

JohnPelletier
Alteryx Alumni (Retired)

@mchamlee You should probably file a defect. If it's just a file format or environmental issue, the support team will sort it out, and if it's a legit defect, that's the best channel to get it fixed. 

 

Have any other readers here seen this problem?

lepome
Alteryx Alumni (Retired)

@mchamlee 
I'm not sure I agree with @JohnPelletier  about one aspect of his recommendation:
If you have a paid license, you can absolutely open a case with Support to get assistance.  The part I don't agree with is the conclusion that this might be a defect/bug.  I think there may be more troubleshooting you can do before concluding that it's a defect.

You might already have done this, but please verify that you can upload using the Swagger test portal.  <yourURL>/webapi//swagger/ui/index#!/Workflows/Workflows_CreateWorkflow after entering your Admin Key and Secret at the exclamation point.

This might help you troubleshoot.This might help you troubleshoot.

mchamlee
6 - Meteoroid

@lili Thank you. With your note I was able to follow a path to resolution. I had previously tried the Swagger page to test Workflow uploads, but had ran into an issue/complication (don't recall now what it was) that caused me to move to the Alteryx provided Postman Collection. After trying again today via the Swagger test and having success I reviewed the Postman collection and found the issue there. What is provided for the v3/workflows endpoint sets the Body Content Type as 'x-www-form-encoded', which as I learned is not sufficient in this case. After moving the required parameters to 'form-data' I was able to successfully upload from Postman as well. I will next modify my Python code to align with this requirement, but I expect I will have success from this point forward.

Yongcan
8 - Asteroid

Thanks , these toolkits are very handy and helpful.

 

Recently we are upgrading to version 2022.1.1.25127, the API is not working on UAT some times and it was fine with our DEV gallery , the only difference is on UAT we have Load Balance of  'Round-Robin' to Primary/Standby Gallery host. 

 

 

Still working with alteryx support to identify the root cause, based on how OAuth 2.0 works.

We suspect the Access/Bearer token is from one gallery and the resource request goes to another gallery and end up with HTTP 401 error.

 

Any one with similar set up and is API works with LB. is it configuration issue with LB or gallery api interface? ( didn't find related instruction about how to set up for such case)

 

 

Issue assumption:

Yongcan_0-1656911571438.png

 

@lepome  could you help take a look?

 

Update:

2022-07-04: We are exploring if it could be fixed from Load Balance configuration, find a solution called "sticky feature" under AWS Elastic Load Balancer (ELB) at <https://medium.com/@kennith/elastic-load-balancer-and-oauth-2b6ef2513e9b> ,as our Load Balance based on other product and it also come with similar function, checking with support team if such option could resolve our case.

lepome
Alteryx Alumni (Retired)

@Yongcan 

This is not my area of expertise.  I defer to the support team.

NicolasSz
11 - Bolide

Hi @DanH 

 

Thanks a lot for this, it's awesome.

We are going to migrate our server to 2021.4 and I'm going to use your macro pack to remove all my C# script that I use to do couple of maintenance and operational tasks. (Triggering workflows, downloading workflows and migrating workflow mainly)

For that, I'm going to adapt your macro so it also calls method from the API v1.

This would give us more flexibility with our administrative tasks.

 

Regards

Yongcan
8 - Asteroid

Quick update on our issue regarding load balancer , once we update the LB configuration with "sticky feature" enabled that route same client to same gallery. our issue resolved. 

 

My issue above.

Link: https://community.alteryx.com/t5/Engine-Works/Introducing-the-Alteryx-Server-v3-API/bc-p/962867/high...

 

AlteryxUserFL
11 - Bolide

I get an error "AlteryxConnectorEngine.dll" could not be loaded: The specified procedure could not be found." when I try to run... any thoughts? 

 

AlteryxUserFL_0-1659965038217.png

 

yuriy
8 - Asteroid

@DanH, Can we please get a sample workflow included as an attachment instead of just a screenshot? I am a bit puzzled about what is going on in the formula and record id tools, also what two inputs are required for the API macros.

Thank you

Tanai_Goncalves
8 - Asteroid

Hello,

 

I`m having some network issue trying to retrieve the Bearer Token.

 

Tanai_Goncalves_0-1661649996578.png

 

 

Error: Download (49): Error transferring data "https://*****.****.com/webapi/v1/workflows/subscription/oauth2/token": Failure when receiving data from the peer

 

When I manually input the Bearer Token all commands (GET, PUT, POST) work just fine both with V3 and V1 endpoints.

 

Is there some default network configuration to allow the POST from the "Server API Authenticate" before having the Bearer Token?

 

Kind regards,

 

Tanai

JohnPelletier
Alteryx Alumni (Retired)

I would open a support ticket and they can help you solve this problem. OAuth2 is a 2-step process to get the bearer token, and if you don't have the redirect URL set up properly this can happen. OAuth1 was simpler, but less secure.

JohnPelletier
Alteryx Alumni (Retired)

@cAral I hope you've solved the problem by now, but if you haven't it looks like you have a problem with the body of your request. It's expecting settings for OtherUsersMayDownload and OtherUsersMayExecute, and interpreting them as false. If you take a valid GET response and modify only what you want to change, then use that as the body for your PUT, I believe you'll be successful. It should ignore fields that can't be changed, but you're sure to have the right format for the other fields.

Linas
8 - Asteroid

Thanks for creating these macros! Could the /v3/collections GET request be expanded to include the view parameter as shown in the picture? Right now I cannot find a way to query the full information about collections.

Linas_0-1671527250443.png

 

Thableaus
17 - Castor
17 - Castor

Hey @Linas which version are you in? I can use this parameter (2022.1)

Linas
8 - Asteroid

Hi @Thableaus , my mistake. For noobs like me, you have to create an additional field with the field name being the name of the parameter and value as the value of the parameter. Finally, plug it into P input.

bny_abo
6 - Meteoroid

Dan Hilton

 

These macros are awesome .... two questions:

 

1. Where are the full documentation around the usage of the macros?

2. Any advice on if the output should be json/xml and what tools are best to read the output?

hroderick-thr
11 - Bolide

I truely appreciate these macros. They are well thought out.

 

I do believe I spotted a bug...

From getting workflows in the versionNumber is always zero. 

It should be 1 through where n is the number of versions.

rymatt830
7 - Meteor

Hi Everyone. I'm receiving a HTTP/1.1 501 Not-Implemented error with the V3 POST API when selecting the action "Upload a new version to an existing workflow." The other two actions execute perfectly fine without any errors. I've researched the message and found HTTP/1.1 is returned when "... the server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource."

 

Has anyone else run into this issue before with the new V3 POST API tool?

hroderick-thr
11 - Bolide

@rymatt830 Check the API Documentation swagger on the machine it is running.  I had a problem using documentation for latest V3 to download a workflow. It turned out the endpoint I needed was not on the older V3 from my 2021.4 version

 

That may not be it but it is easy to check :)

rymatt830
7 - Meteor

@hroderick-thr your suggestion led me to the solution! The workflow I'm using - available from the public gallery - uses a POST tool instead of a PUT tool to upload a new version of an existing workflow. I realized PUT is the appropriate tool for this task after following your suggestion and reviewing the API documentation for the server. Thank you!

levell_x_dunn
10 - Fireball

Is there a list of which V3 API is user base vs Admin only?

mgrajkumar
7 - Meteor

Does  the 3 API works with windows authenticated server instances?. Iam getting error while using the authenticate macro

 

Server API Authenticate (1) The response headers from https://xxxxxx/webapi/oauth2/token were HTTP/1.1 401 Unauthorized  @DanH 

 

Shingo
Alteryx
Alteryx

Hi @DanH 

 

A customer is using Server API to upload workflows via workflow with API macro. After they upgraded Server version from 2020.3 to 2023.1, V3/API Workflows – Upload a new workflow start to hit an error/warning below.

I could reproduce the same error on my 2023.2 server with a simple workflow.

From Server API page, this API looks working fine and can upload new yxzp files to the server.

 

Warning: Server API POST (5): The request to http://localhost/webapi/v3/workflows failed with an HTTP 400 Bad Request error. Error message: The request is invalid. 必須。 Record ID: 1 (必須=Required.

 

 

画像1.png

Do you have any idea to avoid this error.

Best Regards, Shingo

henrymk5
7 - Meteor

Does anyone know how to use the macro to pull V1 endpoints?