API connections give access to many web-based applications, database systems, or programs by exposing objects or actions to a developer in an abstracted format that can easily be integrated into another program. In other words, an API functions as a point of integration where you can programmatically access or manipulate information for a program (or workflow) you’re building. In the context of Designer use, APIs are most often used to access data stores, utilize web-hosted services while blending, or to build connectors.
Most APIs are in RESTful architecture, the software architectural style of the World Wide Web, and typically communicate over HTTP with the same HTTP actions, or “verbs”, that web browsers use to retrieve web pages and transfer data: GET, POST, PUT, DELETE, among others. As such, any tool or software that gives you the ability to use the HTTP request-response protocol will let you communicate with these RESTful APIs. The three I most commonly use to establish my connections are Postman (a great testing app that resembles the Alteryx Download Tool configuration), cURL (a command line tool and one of the predominant HTTP/FTP transfer libraries), and everybody’s favorite software: Alteryx. Between these three tools, and maybe a web traffic monitor like Fiddler (this will let you see the HTTP requests being sent/received over your network), you should be able to establish, maintain, and automate connectivity to just about any REST API of your choosing. This article briefly exposes how to do so in cURL and Alteryx so that you can (1) easily pivot between the two for more robust troubleshooting/implementation and (2) more readily implement API connections into your Alteryx workflows, even when they are documented programmatically.
Alteryx Designer
The first step in establishing an API connection is to locate the developer documentation. The quality and detail of documentation for an API is often the limiting reagent of establishing a connection, so be sure to use an API that has the best functionality, then documentation. The documentation will then help walk you through the API’s authentication before introducing the different requests you can make. Since cURL is frequently used amongst API developers, you’ll notice many of the example requests you are introduced to will be in cURL syntax. Being able to decipher those cURL requests will help you easily recreate it in a program with an interface, like Postman or Alteryx. Consider the GET and POST requests below (all included in the attached v10.6 workflow for reference – please note that the workflow will not run due to redacted credentials to the API):
The documentation gives us a URL to communicate with via an HTTP action (two in this case, GET and POST), specific to this request of listing users on search criteria: http://community.lithium.com/community-name/restapi/vc/search/users. It also notes a parameter, or argument, to accompany the request – those keywords are most often associated with the request payload. Along with a payload argument for authentication (redacted), we’ll use these elements to generate our requests. For the cURL requests, feel free to use the executable installed along with your Alteryx Designer, located in C:\Program Files\Alteryx\bin\RuntimeData\Analytic_Apps\ by default (you can get your own download here).
GET
Request in cURL (command line):
(the –i option is used to include the response headers to resemble the Alteryx format below)
Request in Alteryx Download Tool:
POST
Request in cURL (command line):
Request in Alteryx Download Tool:
Note: A series of cURL commands can also be implemented into a .bat file to be executed within a workflow via the Run Command Tool(master it here).
Translating the Requests
Above you can see side by side examples of cURL syntax and how the API request would look in the Designer. While we can’t go over every type of request you may need, we can equip you with a metaphorical pocket dictionary that will help you translate between the two:
- The URL in your cURL request will simply need to make its way to the URL Field in the Basic Tab of the Download Tool.
- Timeout time (--connect-timeout in cURL) can be changed in the Connection Tab.
The schematics below identify some of the elements from our lookup table, but in syntax:
Additionally, Postman, the tool mentioned earlier, can build requests much like in Alteryx and has a “Generate Code” feature that will convert the request to usable cURL syntax that can be helpful in translating.
While the above helps elucidate some of the similarities between cURL and Alteryx HTTP requests, there are also some notable specificities to using each. For example, cURL will give you far more control over the more granular configuration options for each request; things like what version of HTTP to use, passing cookies, using proxies, among others. Alteryx, on the other hand, gives you the flexibility to build an entirely different request from each row of data entering the Download Tool, making it near effortless to generate a large number of requests customized to your data or to automate API interactions that would otherwise require daunting programming. In addition, Alteryx makes it far easier to parse an API response into usable data such that it can be blended with your other datasets – all inside the same workflow that made the requests. Depending on the types of requests you’ll be making to your API, you’ll have to look at the different formats above and determine the optimized approach. For example, what if you need very specific request configuration but see yourself making a large number of requests? You could use Alteryx to automate writing all the syntax of your cURL commands to a .bat file, and then run that .bat file in a Run Command Tool from Alteryx. Now that you know both, choose wisely!