Alteryx Server - Gallery API Postman Collection

[FlorianC]

Alteryx x Postman

Alteryx Server enables organisations to take the next step in analytic process automation (APA) to scale, share, and govern their analytic workflow processes, models, and data.

Server is accessed through a front-end interface called the Gallery. It is a single platform for users to search for assets, collaborate, and execute processes in a controlled way.

What is best for users however, might not be what administrators expect. Indeed, from an IT perspective, anything that requires manual intervention might be seen as a risk that you want to reduce. For this purpose, Alteryx Server can be called programmatically through its Gallery API.

In this article, we are going to review what the Gallery REST API is, what resources are available, and how to use it with Postman.

---

Table of Contents

• Introduction
• What is an API?
• What is a REST API?
• What is OAuth?
• Alteryx Gallery REST API
• Overview
• Documentation
• Static documentation
• Interactive documentation
• Postman
• Postman API Client
• Postman Collection
• Practical example
• Configuration
• Calling the API
• Queueing the job
• Checking the job status
• Retrieving the output
• Links
• Additional resources

---

Introduction

In this section, we are going to introduce the important concepts and terms used when talking about APIs.

What is an API?

For those of you that may be unfamiliar with what an API is, let us first have a look at the definition we can find on Wikipedia:

An application programming interface (API) is an interface that defines interactions between multiple software applications or mixed hardware-software intermediaries.

In layman's  terms, an API is a way to interact programmatically with an application. This means that you can define a series of steps to automate their execution without manual interaction.

What is a REST API?

Once again, let us use Wikipedia as a reference and a starting point to define what a REST API is:

Representational state transfer (REST) is a software architectural style that was created to guide the design and development of the architecture for the World Wide Web. REST defines a set of constraints for how the architecture of an Internet-scale distributed hypermedia system, such as the Web, should behave. The REST architectural style emphasises the scalability of interactions between components, uniform interfaces, independent deployment of components, and the creation of a layered architecture to facilitate caching components to reduce user-perceived latency, enforce security, and encapsulate legacy systems.

REST has been employed throughout the software industry and is a widely accepted set of guidelines for creating stateless, reliable web APIs. A web API that obeys the REST constraints is informally described as RESTful. RESTful web APIs are typically loosely based on HTTP methods to access resources via URL-encoded parameters and the use of JSON or XML to transmit data.

A RESTful API is thus a web API that is adhering to pre-defined industry standards. This means that concepts that are applicable to one RESTful API will be applicable to another, making their usage easier for the consumers.

What is OAuth?

You might have guessed it, we are going to refer to Wikipedia once more:

OAuth (Open Authorization) is an open standard for access delegation, commonly used as a way for Internet users to grant websites or applications access to their information on other websites but without giving them the passwords.

The important concept here is that OAuth enables users to authenticate to various platforms without having to give away their credentials.

Should you be interested in learning further about OAuth, everything is explained in detail on their website: https://oauth.net.

Alteryx Gallery REST API

Alteryx Server exposes an API for its Gallery component, the front-end through which the users interact.

Overview

The Gallery API is made up of four APIs:

• Subscription API: Endpoints for users to interact with subscriptions, workflows, and schedules (jobs).
• User V2 API: Endpoints for users to interact with credentials, input files, and schedules (jobs).
• Admin V1 API: Endpoints for admins to fetch resources from the Admin interface.
• Admin V2 API: Version 2 of the endpoints for admins to fetch resources from the Admin interface.

Documentation

Static documentation

The Gallery API is documented in our online documentation.

Interactive documentation

Interactive documentation is also available directly within your Server instance.

• Private instance: http://%hostname%/gallery/api-docs/
• Public instance*: https://gallery.alteryx.com/api-docs/

*You will not be able to interact with the Public Gallery API unless you have a key.

---

Postman

Postman logo

Postman API Client

Postman describe themselves in the following words:

Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs—faster.

It offers a lot of features that are outside of the scope of this article. For our purpose, we are going to focus on its API client. You can also use their Public API Network to discover new APIs and collections that have been made available by others.

Postman Collection

Postman collections are executable API descriptions. It enables users to create requests and examples that are interactive.

The Alteryx Server Gallery API Postman documentation is publicly available at the following address: https://documenter.getpostman.com/view/14766220/TzeUmTWD

You can import this as a collection within one of your workspaces to use.

Please refer to the usage section for additional information on how to configure and use the collection within your environment.

---

Practical example

Let us use a practical example to demonstrate how to use the Postman collection to call the Server API.

I have a workflow on my Alteryx Server that retrieves the latest euro references foreign exchange rates from the European Central Bank (ECB) website.

It produces a single output file containing the rates for all currencies.

The aim of this exercise is to obtain the output file without opening Alteryx Designer or using the Gallery front-end interface.

Alteryx workflow

Configuration

The first step is to configure the Postman collection to make sure we are using the correct Gallery URL and credentials.

All the information required can be found under the Keys section in the user profile on the Alteryx Server.

Alteryx Gallery User Profile

We will then head over to Postman, and navigate to the Environments section, select the Alteryx environment, and update the current values accordingly.

Postman Alteryx environment variables

Important Make sure to set Alteryx as the current environment in the top right-hand corner.

Finally, we need to set the reference to the application (i.e. workflow) that we wish to execute. To do this, we need to retrieve the unique identifier (ID) of the workflow. This is displayed in the URL of the workflow in the Gallery.

Alteryx application ID

We can then enter this value in Postman. The configuration for this is located in the collection itself, under the Variables section.

Postman collection variables

Calling the API

Now that we have set up the configuration, we can select the API endpoint or method that we want to use.

In this example, we are going to go through three methods of the subscription API:

1. Queue job: Queue an app execution job.
2. Jobs: Retrieves the job and its current state.
3. Output: Returns output for a given job.

Queueing the job

To queue the workflow for execution, expand the subscription folder and select the Queue job post request.

Two variables are used in the request URL:

1. gallery-url: The URL of the Alteryx Gallery configured in the environment.
2. appId: The ID of the workflow we want to execute.

Click on the Send button to send the request and see the response in the bottom panel.

Queueing the job

Check the status of the response (see list of HTTP status codes) then the body which is in JSON format and shows that the job was queued successfully.

{
    "id": "615d9d830d49000060007b20",
    "appId": null,
    "createDate": "2021-10-06T12:58:43.1081992Z",
    "status": "Queued",
    "disposition": "None",
    "outputs": [],
    "messages": [],
    "priority": 0,
    "workerTag": "",
    "runWithE2": false
}

Checking the job status

Now that we have queued our job, let's check if it is done and if it was ran successfully. We can get the job ID from the response of the previous request, and use it as a parameter to query the status of the job.

Job ID variable

We are then going to open the Jobs get request in the subscription folder.

Two variables are used in the request URL:

1. gallery-url: The URL of the Alteryx Gallery configured in the environment.
2. jobId: The ID of the job we want to query.

Query job status

Always check the response code, then the body and look for the status of the job and its disposition.

We can also see that one single output was produced output.yxdb.

{
    "id": "615d9d830d49000060007b20",
    "appId": null,
    "createDate": "2021-10-06T12:58:43Z",
    "status": "Completed",
    "disposition": "Success",
    "outputs": [
        {
            "id": "615d9d860d49000060007b23",
            "formats": [
                "Shp",
                "Tab",
                "Mif",
                "Dbf",
                "Csv",
                "Raw",
                "Tde"
            ],
            "name": "output.yxdb"
        }
    ],
    "messages": [
        {
            "status": 1,
            "text": "1 record was output",
            "toolId": 6
        },
        {
            "status": 101,
            "text": "action:GET URL:https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml",
            "toolId": 7
        },
        {
            "status": 1,
            "text": "Records transferred: 1; active connections: 1; average records per minute: 26",
            "toolId": 7
        },
        {
            "status": 1,
            "text": "32 records were successfully parsed and 4 were not.",
            "toolId": 10
        },
        {
            "status": 1,
            "text": "32 records were True and 4 were False",
            "toolId": 12
        },
        {
            "status": 9,
            "text": "output.yxdb|32 records were written to \"output.yxdb\"",
            "toolId": 8
        }
    ],
    "priority": 0,
    "workerTag": null,
    "runWithE2": false
}

Retrieving the output

After the successful execution of the job, the ID of the output file generated can be retrieved from the previous call response.

We are going to reference this value in the corresponding outputId variable.

Output ID variable

We are now going to open the Output get request from the subscription folder.

Three variables are used in the request URL:

1. gallery-url: The URL of the Alteryx Gallery configured in the environment.
2. jobId: The ID of the job we want to query.
3. outputId: The ID of the output we want to retrieve.

Because the job ID has already been configured previously, we do not have to reference it again.

Raw output

Notice that this time, the response is illegible. This is because the output is returned as raw binary data. You can use Postman to save it back to a file using the save response button on the top-right-hand side of the response panel.

Save response

That is it. We have successfully triggered a workflow and retrieved the output file using the API.

---

Links

Alteryx Server API Postman collection: https://documenter.getpostman.com/view/14766220/TzeUmTWD

Additional resources

1. Gallery API Overview: Static API documentation
2. Public Gallery API: Public Gallery API interactive documentation
3. Using the Alteryx Gallery API: How to use the Gallery interactive documentation
4. Excel to Alteryx API: How to call the Gallery API from Excel
5. Postman official website: What is Postman?
6. Postman Learning Center: Learn how to use Postman
7. alteryx-api-postman: Alteryx Gallery API Postman Collection GitHub repository

[Thableaus]

This will be super helpful! Thanks @FlorianC 

[cgoodman3]

I rarely read through the Engine Works but this is a great find. I've used Postman a lot before but essentially self taught so I learnt a lot from this.