Many (and I do mean many) years ago, I found myself hovering near the cube of an esteemed mentor, trying to soak up as many words of wisdom as possible.
I heard this:
If I have to do something manually more than 3 times, I write a script and automate the process in question.– Chris, a very smart person.
Chris was right, of course. Since then I’ve always tried to automate everything, everywhere. The fact that I find it fun to do helps a bunch.
I automate for two reasons:
- It saves me a bunch of time
- I am human, and therefore an expert mistake-maker
Depending on whether you’re a glass-half-full or half-empty type, one (or both) reasons will resonate with you. And there’s some good news…
You don’t have to be a code jockey to automate Server.Next
Have you ever used a command-line tool or written a simple batch script on Windows? Then you too can automate the hell out of Server.Next. Of course, if you can bang out a little code and are familiar with tools like Postman you’ll be a rockstar….
Let’s Get Down to Brass Tacks
Alteryx Server.Next is really nothing more than a bunch of REST Endpoints that do stuff like:
- Provision a new multi-tenant site
- Execute a workflow with Engine
- Store workflows
- Create or modify Data Sources
- Retrieve workflows
- Create Schedules
- Provision Users
- Gather and store metadata from databases
- Configure settings on the Server
If you know how to call these endpoints, you can automate everything. The cool thing about Server.Next is that there is no special, undocumented “secret sauce”.
From an automation point of view, our own front-end website is calling the very same REST Endpoints to get work done that you’ll call. For example, right now I have code in my back pocket that will create a new site, populate it with users, create and upload content, customize that content, and then permission everything appropriately. It’s idiot-proof and nearly Russell-proof.
What tools will I use?
There are a number of resources that you can leverage to spin up and use our endpoints.
Swagger UI (Docs!)
Swagger UI is baked right into Server.Next, and is essentially visual interactive documentation. You can read and try out “REST-y stuff” right in the web browser, make sure you understand how it works, and then use what you learned in other tools. In upcoming posts, I’ll spend a significant amount of time showing you how to use Swagger for best effect.
The Developer Tools that are part of your browser represent a cornucopia of goodness when it comes to understanding which REST endpoints you might want to hit under different circumstances. For example, below I’ve just changed the “Alternate Name” property of one of the folders in my virtual file system with the Developer Tools window open.
Using Dev Tools, I can see the endpoint I need to hit (/api/v1/files), any special Headers that need to be set (none in this case), and the PUT request payload that I’m sending (JSON which points to the location of the path of the thing I’m going to change and the property/value pair to apply ). Watching the calls made by your browser as you “do things” in Server.Next is like a GPS through our REST endpoints.
Advice: just go ahead and download / install now. Seriously. Once you THINK you’ve figured out how an endpoint works, Postman can be your acid test and knowledge repository. All you really need to know how to do is copy and paste text out of Developer Tools or Swagger into Postman. then execute. Once you know “you’re solid” with a particular method, you can add what you know to a Collection of calls for future use.
cURL is a command-line tool for getting or sending data (including files) using URL syntax. You can leverage cURL to GET, POST, PUT, and DELETE against your REST endpoints and make your server “do stuff” right from the command-line (and inside batch files). In addition, both Swagger and Postman can generate cURL command-line syntax for you: Lazy is good.
Let’s put it all together
Let’s say I want to know how to login to Alteryx Server.Next via REST, and I have NO clue how, nor do I feel like actually READING the fine manual that is Swagger UI. Here’s what I might do:
Jump into Dev Tools
First, open up your Dev Tools in Chrome, Firefox, or whatever your favorite browser is. Get to the Network Panel so you can see all the stuff going back and forth between the browser and the website you’re talking to. Now, just surf.
After I’ve logged in, I’ll review the chronologically ordered list of resources I interacted with during the process of logging in. The “authenticate” resource looks like a REST endpoint to me just because of how it’s named. The associated URL (https://sn.russch.com/api/v1/authenticate) that my browser POSTed to is formed (formatted) like most REST endpoints are, too.
So it looks like authenticate is what I’m looking for. Next, I can scroll down in the Headers panel to see exactly what my browser POSTed in the request to the endpoint in question.
In this case, it’s all the information one needs to login – A user name (email), password, and the ID or friendly name of the Alteryx Site I want to login to.
Next up, I might hit https://<my server>/api-docs in order to get into Swagger UI. I know I’m looking for the /v1/authenticate endpoint, so I just search on “authenticate”, and voila: I find the call in question.
Swagger shows me a sample request payload I need to send, and I click Try it in order to…well, try it.
I overtype some of the sample parameter values with the information I need to provide in order to log in. Then, I hit EXECUTE.
Clicking that beautiful blue button causes wonderful things to happen. You’ll get the actual response to your request back so you can see if there are errors and/or what information the server returns to you. Swagger UI also generates a “pretty good” cURL command for you which will return the same result you just got in the browser.
At this point, you’ll know whether you did things right or not, and you have everything you need to move to the “acid test” if you want to bother.
We’ll finish off with Postman. In the real world, it’s unlikely you’d use all three of these tools together all the time, because doing so would often simply be overkill. For simple work, simply copying and pasting the request payload out of Dev Tools is good enough to get you started. No need to look at docs, no need to test in Postman.
That said, Postman IS really good for when you’re dealing with something a bit more complex, or you’re during troubleshooting. Sometimes issues with cookie management or SSL will get in the way, and Postman can handle most of that for you automatically and seamlessly.
In the somewhat contrived example below, We’re starting with a blank request in Postman that we’ll build up based on what we’ve learned from either Dev Tools or Swagger.
- I can see that I need to POST this request based on what Swagger and Dev tools told me. So, I change my verb from GET to POST.
- Next, I plug in the URL of the endpoint I need to hit
- Then it’s time to add the username/password /site information I spotted in both Dev Tools and Swagger into the BODY of my request
- Finally, I add a Header to my request to tell the server that the content-tye of the information in BODY is JSON.
After we send this request, the response indicates all is well via the 200 status code. Inside the larger response body, I can also see the session id that has been created on the server based on my successful login. Finally, I can play around with the Code Generation capabilities of Postman to get some snippets I might use elsewhere. In fact, the cURL command that I fired in an earlier section comes directly from Postman.
Over the next weeks, I’ll be spending a bunch of time blogging about our endpoints. You’ll learn about the most important ones and how to use them. YOU will need access to a Server, however!
And we have you covered: Alteryx has two Server betas underway: The first allows you to leverage an ephemeral virtual machine on AWS that we spin up for you for a limited amount of time. You can sign up for that beta here. The second program gets you an installer that you can drop onto a (virgin) machine. You care for and feed this machine as you see fit with a lot more control and permanence. [NOTE: Only Current Alteryx Customers can participate in these betas. Sorry ’bout that]