How to Connect to a Simple Web API

April 2020 V0.1

Level: Beginner

Introduction

In this document and the accompanying video, we are going to discuss connecting to a web API from inside of Blue Prism. This document will explain in more depth some of the concepts that the video explains.

The video is available at

https://digitalexchange.blueprism.com/site/global/developer/learn.gsp

Along the way, we will discuss API's, REST, request and response. The video demonstrates how to create a connection from Blue Prism to a simple Web API called Kanye-REST.

This API has no parameters and only returns a single value, because of this simplicity, it is an excellent introductory demonstration.

What is an API?

APIs or Application Program Interfaces allow a computer, or more accurately an application to communicate with another application on another computer.

Examples of this functionality might be to move data from one system to another, call into a weather service to get the forecast for an area or to use twitter to get a list of tweets from a user account. API's are everywhere, Google, Twitter, Microsoft, Instagram all have many API's for performing different tasks

An example of API use might be that a dentist has a website that clients can sign up for appointments. The dentist wants to give the ability to create an outlook or a Google calendar event with the appointment details. The API use here would be for the dentist to have their website talk to Microsofts or Googles server to create a calendar entry with the appointment details.

The benefits of this functionality are that this can all happen without the user leaving the dentists web site.

Let's have a REST.

The way that APIs work is through REST. REST is an acronym for REpresentational State Transfer. It is an architectural style for communication across the internet, and it uses a request and response format to pass the data between the systems involved. These mechanisms are called web-services, and those services that work this way are called RESTful.

The information elements accessed by a REST web service are known as resources. Any information that can be named can be a resource. To identify these resources, REST uses a resource identifier to allow interaction between the components involved.

REST is an example of client-server architecture.

Any Requests?

For a resource to be accessed, it must be identifiable by what is known as a URI, or a Uniform Resource Identifier. The URI is a string of characters that unambiguously identifies a particular resource. In our video example, the URI is

https://api.kanye.rest/

Kanye-Rest is a simple API, as it requires no parameters. You can enter the URI into a browsers address bar and, it will activate the API and return you a message from Kanye. We will do this from inside of Blue Prism.

The Verbs

HTTP has nine verbs that define the method of a REST request. Of those 9, there are five that we use most frequently.

Verb Action
POST Create
GET Read
PUT Update/Replace
PATCH Update/Modify
DELETE Delete

In our example, we use the GET method to retrieve our response from Kanye-REST.

The Response

When we get an answer back from our web service, it is known as a response. The response contains either the information we want or some kind of error detailing any issue that may have occurred. HTTP has several response codes that can accompany the response detail.

Status Codes

The codes are numeric and are in groups from 100 to 500.

Code Group Details
1xx Informational
2xx Success
3xx Redirection
4xx Client Error
5xx Server Error

For more detail on specific status codes, check the following link. https://www.restapitutorial.com/httpstatuscodes.html

If your request works correctly, then you will receive a response with a 2xx response code. If things go less successfully, then maybe a 4xx or a 5xx response code will head your way.

Have you met JSON?

The response data, the item we are interested in, is returned in a data format called JSON. JSON stands for JavaScript Object Notation. It's a simple data format, easier to read than XML and less tedious. JSON is effectively a set of key-value pairs that hold the data from a response. Our example, Kanye-Rest, returns a single key-value pair in the form of:

{"quote" : "I am great"}

From the above, 'quote' is the key, 'I am great' is the value. JSON can cope with many data-types, including strings, numbers and objects. Objects are just complex data types that contain other data types. An example of this is an address, and it could look like this:

{

"address" : {

"name":"Jim Smith",

"address1":"The Street",

"town":"Digbeth",

"city" : "Birmingham",

"postcode" : "B5 1AA"

}

}

Remember, this is an example of a complex object shown in JSON. The JSON we work with, in our example is much simpler.

Calling the Kanye-Rest API From Blue Prism

Image 01

From the Blue Prism main screen, select the System tab on the bottom left.

Image 02

From the System Treeview click on Web API Services

Image 03

Click on Add Service in the top right of the main window.

Image 04

Add a name for the service.

For the Kanye-Rest service, there is no need to set any of the Common items. These common items are for parameters and metadata that would apply to all of the methods that this Web API contains. The Common Code menu item is for .NET code. Common Code, is code that you can use in an actions custom code response. We will not discuss coding options here as it is beyond the scope of this document.

Image 05

Modify the Action and give it an appropriate name for what the Action is going to do.

Note that the Action is enabled by default. The Enable Request Data Output Parameter will create an additional parameter on the call that will encapsulate the details of the request, including headers. It can be helpful when debugging to make sure that what you are sending is what you intended to send. Finally, the Disable Sending of Request does just that. It doesn't send your request, again another debugging tool. So, you could make use of a tool such as Fiddler to see if what you think you are posting is correct. This way you don't send anything, it just mocks the request.

There are no parameters needed for this API call.

Image 06

The GET method is all that is needed here. We have no modifications to make to the URL path. Some, more complex, APIs will need an entry here. We can leave the Body Content at None.

There are no headers required for this request.

Image 07

Edit the response, as shown above.

There is a single parameter for the response. It is of a text data type, and it makes use of JSONPath to access the element needed from the JSON payload.

Our work on the Web API definition is now complete. We will now build a simple test harness process to run our definition from and check the results.

The Test Harness Process – Kanye REST Test

In Blue Prism, go back to the Studio tab and on the list, right-click on the word Processes at the top of the list.

Image 08

The create process dialog is displayed where you can name our test process.

Image 09

Give the Process a name and click ok.

The Process is now visible in the studio list under the default group. Double click the Process here, and it will open the process window.

Image 10

Click on the Action tool on the left and drag it in between the Start and End stages.

Image 11

Once in place, double click the action stage and name it accordingly, as shown above. Click on the Business Object drop-down and choose the Kanye REST web API object we created earlier. In the Action drop-down, GET should be selected by default as it is the only action we created.

Image 12

Click the outputs tab, and the screen will look similar to the above, if you click on the button pointed to by the solid red line it will create a text item for you, and it will show it in the list on the right, pointed to by the dotted line. When you save the Process, a data item is created for you in the process window.

Image 13

Now add links from the start to the action stage and then on to the end-stage.

Image 14

Our test process is now complete.

If you click on the small green triangle (small ellipse above) the start stage will turn amber and progress through the next two stages and then stop at the end-stage. If all has gone well, the quote data item contains some Kanye zen.

Further Reference.

HTTP Headers

HTTP Headers can be quite a subject in its own right. The W3C makes the following details available at https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html This is a little dry for bedtime reading. This is part of RFC 2616, and it has a full explanation of all the HTTP headers you are likely to encounter.

HTTP Status Codes

There is a superb resource at https://www.restapitutorial.com/httpstatuscodes.html that provides information on the whole range of HTTP Status Codes.

Tools

Your toolkit is essential, especially when things don't work as expected. Here are a few tools that I use when working with Web APIs.

JSONPath Online Evaluator – https://jsonpath.com

JSON Formatter - https://jsonformatter.org/

Postman - https://www.postman.com/

SOAP UI - https://www.soapui.org/

Katalon Studio - https://www.katalon.com/katalon-studio/

Programmable Web – https://www.programmableweb.com