REST Basic training using Flow and Postman
Some basic examples of how to maneuver in Flow and Postman to ask REST queries.
Prerequisites
A Flow Environment with powers to create connectors and a public user (Permission and license)
Rest Connector License
SQL Server Database connector license (Or some data source to fetch data from)
Postman installed
Terminology
Base address: This training was created using a locally installed Flow environment, so the full url to the flow server in this scenario is: http://localhost:81/Flow.Server (if entered in a browser would show your Flow environments server page). The Base address however in Flow is only the server part of the address, in this scenario http://localhost:81. It could also be what is referred to as FQDN, similar to http://server.company.com.
Data Source: For the examples the SQL Database "Flowington" was used (our internal lightweight fake ERP that we use for testing, training and development). Any data source could be used but then the data would probably be a little different, but with some imagination and adaptability it would not be an issue.
WorkflowId: Every workflow will get its own unique ID, as with Base-url this will be referred to as WorkflowId.
Initial Set-up
Environment - Users: Make sur you have user of the type Public User in your Flow environment with a strong password (that you have access to).
Create the Select Persons Flow
Create a new Machine Flow with a Machine step to fetch some data from a table.
Connect the result of your query to the ouput variables (red ring)
Execute the flow in the debugger (in the studio) to make sure you get some proper results.
Right click on your Flow and choose to Generate Web Link and copy the url
Query your API - GET
From Postman
Open Postman, create a new workspace that you call "REST Training with Flow", and under that collection add a new request as a GET request, pointing to the url you just generated in Flow.
Under Authentication, choose Basic Auth and enter the username and password for your public user in Flow and press Send to make sure you get some data back and a Status 200 OK
Congratulations, you have now build a REST API using Flow, and mastered Postman to successfully query the API (i.e., your Flow) getting a Response Status 200 OK with values.
About Basic Authentication
What the Basic Authentication actually does is encoding the username and password in to an encoded string, and applying that in the request header with Authorization as Key and the encoded string as Value.
In other words, you can choose No Auth under Authorization and instead manually apply the Authorization to the request header. Just to understand the technology
You can also in Postman set the authentication on the workspace folder, and then choose "Inherit Auth from parent" on all the underlying requests to not have to enter it multiple times.
In Flow you can set the Username and Password for basic authentication on the connector (see image further below), and then create an Authorization scheme that you connect to your operations.
Or just as in Postman you can choose to pass an Authorization header with the base64 encoded username:password
From Flow
Now we will use Flow to have one workflow query our first workflow using REST. Albeit this might seem silly, it is a good way to understand the structure and see how it is possible to use Flow both as a back-end and front-end.
Under Environment - Connectors, create a Rest Connector, setting your public user as user under Authentication. The connector will be referred to as "Flow Server REST", so call it the same if you wish. Note that the Base address is just the server part of the url as mentioned earlier.
Press the EDIT button, this is where we are going to create and manage our REST Project.
Inside the Novacura REST Connector Project Window:
Click on Models and then New From JSON
Name the model GetPersonResult
Copy the entire result from Postman into the left pane
Click Preview and verify the result on the right hand side
Press OK
We now have a model of the response body of our request which we will connect to an operation. Create a New Operation that you call GetPerson, with the path that is the same you were using in Postman except the Base address.
And here comes the kicker that is hard to miss, we want to capture the result in to our model that we have created, do so by select Object as type and our Model under the output like so:
Press Create/Update connector to build the Connector Project and then Save out in the Connector property page
Out in Flow, create a new workflow that will use the newly created connector to ask our first flow for data from the Person. Make a habit to always press the Refresh button in the operation selection window after you have made changes to the connector project to fetch the latest changes.
Running our workflow now in the debugger should give us a similar response as when running the first workflow that fetched the data directly from SQL, with the difference that we get the response in a more No-SQL format (not only straight tables, but where a record can contain a record that contain a table etc. More of a JSON structure)
Note also that the response comes in under the OK variable under Persons, just as how we mapped the Operation when we built the connector project. While 200 - OK is the most common code that indicates a successful operation it might differ. So it is important to check the documentation for the REST API for what to expect.
Another congratulations is in place, you have now not only built your own REST API but also created a REST Connector Project in Flow and a workflow that can query your API with a GET request.
Query your API - POST
There are a few different methods to send data in the world of REST. The most common are: GET, PUT, POST, PATCH and DELETE. In our last example we used GET, which would mean something like "Read only" (although there are no technical limitations in the protocol to manipulating data using GET, but that is rarely seen). A quick overview of them could be:
GET: Read only
POST: Insert
PATCH: Update a record with just the parameters provided
PUT: insert, replace record if it already exists
DELETE: Delete record
Make a copy of you Select Persons workflow (the machine flow that queries the database) and call it "Select Persons with Input variable"
Edit the green ring and add a variable that is called PersonId, and use that in your SQL Query for the where clause as shown below:
Right click on the newly created workflow and choose "Generate web link", but this time select POST as the method and copy the input body
Over in Postman, create a duplicate of your "Get Persons" operation, change it to a POST command and paste your copied Input Body in to the body of the request. Set the input variable to 'ALMA' and try to send your request. It should yield a result of only one record (the person ALMA)
To do the same in Flow, go back in under your REST Project and:
create a new model
a new operation with your new workflow as path and POST method..
..and with your newly created model as a body input parameter.
Duplicate your Get Persons workflow and call it POST Persons, double click the cog wheel and change the operation to you new PostPersson operation (do not forget "refresh"). Execute the workflow and validate that you get the same result as with Postman.
Congratulations yet again, you now master POST operations and how pass values in the request body from both Postman and Flow. There is a big world out there in the world of REST that you hopefully with these simplistic examples above feel that you have a rudimentary understanding of ,and feel ready to take on.
Last updated
