07. Connecting to Cloud Services

In an earlier section, we used the Web Request 2 Node to interact with the employee web service. While this is an example of a cloud service, we had to manually figure out the URL and parse the response coming back.

In most real world scenarios, we want the connector to help us by providing a list of supported calls (interactions) and allowing us to see schemas or samples request and response payloads.

Both of these features are provided when we interact with the two most popular standards for web services - REST and SOAP. In this section, we're going to see how to use the REST Request and SOAP Request 2 Connectors for each of these respectively but before we get to that, it will be helpful to have a high level understanding of the HTTP protocol that underpins both REST and SOAP.

HTTP

HTTP (Hypertext Transfer Protocol), is the fundamental protocol used on the internet. It defines the rules for how data is exchanged between a client (for example a browser or other app) and a server.

When you type a URL into your browser or click a link, your device sends an HTTP request to the server asking for a specific webpage or resource. The server then responds with an HTTP response, delivering the data (such as the text, images, and layout) that makes up the webpage, which your browser displays.

Below is a simplified example of an HTTP request for google.com. In other words, this is what your browser will send when you request that webpage.

GET /complete/search?... HTTP/1.1
Host: www.google.com
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)...
...
Connection: keep-alive

GET is an HTTP verb - it shows the action that is performed, in this case we are retrieving an existing resource. Here are some common HTTP verbs:
- GET retrieves an existing resource
- POST generally creates a new resource
- PUT generally updates an existing resource
- DELETE deletes a resource
/complete/search?... is the location of the resource at the Host specified. In other words, the full URL is https://www.google.com/complete/search?...
Host is an example of a request header. The value for the Host header is www.google.com. This tells the server that the request is intended for the domain www.google.com.

When a request like the one above is received, the server will send a response like this one:

HTTP/1.1 200 OK
Date: Wed, 06 Nov 2024 12:00:00 GMT
Content-Type: text/html; charset=UTF-8
...
Connection: keep-alive

<html>
...

200 OK is the HTTP response code and description indicating that the request was successfully fulfilled. Here are some common HTTP status codes:
- 200 OK indicates success
- 404 Not Found indicates that the resource being referenced does not exist
- 401 Unauthorized indicates that the consumer is not authorized to perform the request
- 500 Internal Server Error indicates a problem occurred while processing the request
Content-Type is an example of a response header. This header is telling us the type of content that follows in the body.
<html> is the start of the response body. In this case, based on the content type of text/html, this is an HTML document but it could also have been a binary document like a PDF or ZIP file.

REST services

REST (REpresentational State Transfer) is a modern type of API that will generally be available for apps and services that were "born in the cloud". REST's philosophy is to align closely with HTTP by reusing it's concepts. Specifically, the HTTP verb indicates the action to take while the URL identifies the location of the resource the action should be taken against.

Here are some examples of the way a REST API for an eCommerce platform might work.

Retrieve a list of orders after a certain date:

GET /orders?startDate=2020-01-01

Retrieve the details of a specific order:

GET /orders/10023

Create a new order:

POST /orders
Host: api.someclouderp.com
Content-Type: application/json
...

{
	 "customerId": 123,
	 "orderId": "456",
	 "lines": [
			{
				"stockCode": "abc",
				"quantity": 1
			}
	 ]
}

In Flowgear, you'll use the REST Request Connector to interact with a REST service. The Connector will handle authentication for you and also make samples available of the different interactions that are supported. This is made possible by a standard called OpenAPI (formerly Swagger) which is a document that describes all of the supported operations along with their request and response payloads.

Exercise 08: Pet Store

In this exercise, we'll connect to a demo pet store service, then we'll add a pet, query a pet by its id and finally get a list of all available pets.

In a new Workflow, add REST Request and rename it to add pet
Create a new Connection on add pet and then edit it (click ✎).
In the Connection Pane, set OpenApiUrl to https://petstore.swagger.io/v2/swagger.json.

https://petstore.swagger.io/v2/swagger.json is the location of the OpenAPI (Swagger) document that describes the service we'll connect to - you can open this URL in a new browser tab to see what this document looks like.

When you're connecting to a REST service for the first time, you need to establish the URL for the OpenAPI definition of the service. This will generally be prominently shown in the help center of the third party app or service.
Set Url to https://petstore.swagger.io/v2.

This is the base URL of the actual REST service and should also be prominently announced in the third party app or service help center.
Click Refresh Metadata (you may need to scroll down to see this button).

Refresh Metadata queries the service information at the location provided in OpenApiUrl and stores a copy of it within Flowgear.
Save the Connection, but note that testing it is not required, as it will return a "(404) Not Found" Error. After saving, return to the Workflow.
On REST Request, click v → Choose Sample and choose the addPet sample.

The Node Properties will be updated to configure the Node for an addPet call.
Open the value for Request to see the structure of the document that is expected. Remove all fields except name, tags and status in order to create a simpler request like this one:
```
 {
 	"name": "dog",
 	"tags": [
 		{
 			"name": "large breed"
 		}
 	],
 	"status": "available"
 }
```
Add another REST Request and rename it to get pet.
Set get pet.Connection to the same Connection you have assigned on add pet.Connection.
Select the sample getPetById on get pet.
Connect add pet.Response → get pet.petId, the mapping expression on this Flow Connector to the id Property (click fx on the Flow Connector and pick the id Property from the list).
Connect Start.RunNow → add petand add pet → get pet.

Run the Workflow to confirm that the detail of the pet created in add pet are being returned in get pet.Response.

For one last variation, we'll now filter for all pets with a specific tag.
Add another REST Request and rename to filter pets.
Assign the same Connection as the other two REST Request Nodes to filter pets.
Select the sample findPetsByTags on filter pets.
Set filter pets.tags to `large breed.
Connect get pet → filter pets.

Check that filter pets.Response is showing the large breed pets you've just added.

Save and run your Workflow, then click Submit Exercise to grade it.

SOAP Services

The other type of web service you'll frequently need to connect to, especially in enterprise environments, is a SOAP (Simple Object Access Protocol) service.

While SOAP services usually run on top of HTTP, they aren't as integrated into it as REST services.

Just as an OpenAPI document describes a REST service, a WSDL (Web Service Definition Language) document describes a SOAP service. In fact, one advantage of a SOAP service is that the location of the WSDL can normally be inferred automatically as there is a higher level of standardization than in the case of REST.

Exercise 09: Calculator

In this exercise, we'll connect to a calculator SOAP service.

Add SOAP Request 2 to a new Workflow, rename it to calculator
Create a new Connection on calculator, then edit it (click ✎).
In the Connection, set Url to https://zorkco.flowgear.net/calculator?auth-key=lCQmYr-Fww9UJncjS8k7wCLEVqUQrm__hnsp9X7qrpQyY2lMGChPX8bzTA-JmQkTmDhuKUgnrhdNbwRmIWRBHA.
Click Refresh Metadata (you may need to scroll down to see this button).

Refresh Metadata queries the service information and stores a copy of it within Flowgear. If the WsdlUrl Property is left empty, the Connector will attempt to infer the location of the WSDL.
Save and test the Connection, then return to the Workflow.
On calculator click v → Choose Sample and choose the Add sample.
Add Variable Bar and rename to inputs.
Add inputs.number1 and inputs.number2.
Set inputs.number1 to 40 and inputs.number2 to 2.
Add Custom Properties calculator.number1 and calculator.number2.
Add Flow Connectors inputs.number1 → calculator.number1 and inputs.number2 → calculator.number2.
Edit calculator.RequestXml so that it references the Custom Properties. It should look like this:
```
<Request>
	<intA>{number1}</intA>
	<intB>{number2}</intB>
</Request>
```
Add Variable Bar to the right of calculator, rename it to outputs.
Add outputs.result.
Add calculator.ResponseXml → outputs.result, the mapping expression on this Flow Connector to Response (click fx on the Flow Connector and pick the Response Property from the list).
Add Start.RunNow → calculator.

Run the Workflow and you should see the value 42 being returned in the result Property of the Start Workflow Log.

Save and run your Workflow, then click Submit Exercise to grade it.