This tutorial assumes that you have completed the previous tutorials.

Representational State Transfer (REST) services provide the ability to use services that focus on a system’s resources and how they can be transferred over HTTP, using HTTP methods.

In this tutorial you will access a Google RESTful service that is a basic URL shortener. Using this RESTful service you will create a VPD process that lets you pass in any URL and receive back a shortened version. You will use both a GET and POST method.

Prerequisites:

•Attachmate Verastream Process Designer, including Process Design Studio and Process Server, installed and running.

•Some familiarity with the other tutorials or experience build-ing simple BPEL processes in Process Designer.

•Internet browser

•Some familiarity with RESTful services, XPath, and BPEL.

Let’s get started.

CONTENTS

Using RESTful methods

Getting started with the RESTful service API documentation

Creating the POST project

Configuringthepropertiesof the RESTful extension activity

Getting the shortened URL

Assigning the response to the output

Deploying the POST process

Testing the POST process

Creating the GET project

Setting the GET project properties

Assigning the response

Deploying and testing the GET process

Tutorial 9: Invoking a RESTful Service

2

The RESTful extension activity provides support for the RESTful methods: GET, PUT, DELETE, and POST.

JavaScript Object Notation (JSON) is a popular format for interacting with RESTful services. If a RESTful service returns JSON, it is, whenever possible, converted to XML to make it more convenient to use in the Design Studio.

METHOD WHAT IT DOESGET Retrieves a resource

PUT Updates or changes the state of a resource

DELETE Removes a resource

POST Creates a resource on the server

In this tutorial you will create two projects. One uses the Google URL shortener RESTful service and the POST method to create a VPD process that you can use to pass in any URL and return a shortened version.

The second project uses the GET method in a simple process that allowsyoutopassintheshortenedURLobtainedwiththefirstprocess and return the original lengthy URL, verifying the accu-racy of the service.

Using RESTful Methods

3

The RESTful service API documentation is

the source of valuable information you will use to create your process.

It is very important that you are familiar with the RESTful service you are

invoking.

For this tutorial we’re using the Google URL Shortener API documentation available here: https://developers.google.com/url-shortener/v1/.

Whenever you are using a RESTful service you must refer to the documentation provided with the service. Because RESTful servicesdonotuseWSDLfileslikeSOAPservicesdo,theDesign Studio does not have information available to help you use the service. Therefore, you must rely on the service API documentation.

1. In your browser, open https://developers.google.com/url-shortener/v1/.

2. Note that the RESTful service is using an Insert method to create the new shortened URL.

3. Click Insert to access the HTTP request path: https://www.googleapis.com/urlshortener/v1/url. You will use this path in your VPD project.

Getting Started with the Service API Documentation

4

Creating the POST project

In this project we are using the POST method to shorten a URL. Later the GET project will verify the accuracy of the service.

1. In the Design Studio, from the File menu, click New Project.

2. In the New Project dialog box, name the new project, POST_Restful_svcs. Click OK.

3. In the BPEL Editor, delete the DoSomethingHere place-holder, along with its Assign activity.

4. Insert a RESTful extension activity between the ReceiveInput and ReplyWithOutput.

5

ConfiguringthepropertiesoftheRESTfulextensionactivity

1. With the RESTful activity selected, on the Details tab of the Properties panel, set the Request method to POST. This communicates what method the RESTful service is using within the BPEL process.

2. Enter the URL https://www.googleapis.com/urlshort-ener/v1/urlinthePathfield.

3. Open the Body tab. Type {"longUrl":""}. You’ve now created a request body.

4. We want the process to take any URL as input so the request needs to contain the input payload to the process. Place your cursor between the second quotation marks and click to open the Expression Editor.

5. Open request:InputMessage and double-click request: payload/tns:Input.This inserts the input into the request body.

6. Save the project.

Both the request method and the path are deter-

mined by the RESTful service API documentation.

In the API documentation you can find an example

of the request body in JSON format. This is the

information you’re sending to the service. In this

example the value of the long URL is what you are

passing to the service.

6

The output variable con-tains the response from the service. The response is sent back in two formats: Raw response, a string representation of what comes back, and XML response, which returns an XML element.

From looking at the API documentation, you know that the service returns JSON. The Raw response contains the JSON that is returned from the RESTful service. The XML response results from converting JSON to XML.

Process Designer attempts to convert all responses to XML - if this is impos-sible - the RAW response is always available.

In this tutorial we’re using the XML format.

You will use the Assign activity to get the shortened version of the URL returned from the RESTful service and assign it to the output of the VPD process.

1. From the Palette, drag an Assign activity to the BPEL Editor between the RESTful activity and ReplyWithOutput. Change the name to AssignShortURL.

2. To assign the shortened URL to the output of the service, click to open the Copy Rule dialog box. Select Expression from the From drop down list.

3. You will use XPath to extract the shortened URL returned from RESTFUL service. The XPath expression is: $RESTfulOutput/extensions:XMLResponse/id/text(). The‘id’elementisspecifiedbytheAPIdocu-mentation. You can enter the expression in the Copy Rule dialog box or use the Expression Editor to create the XPath expression.

4. Click OK to return to the Copy Rule dialog box.

Getting the shortened URL

7

Assigning the response to the output of the process

1. In the Copy Rule dialog box, assign the XPath expression to the response payload.

2. Click OK. The copy rule is inserted into the Properties panel of the AssignShortURL activity.

3. Save the project.

The POST project is complete. The next step is deploy and test the process.

8

When you install Process Design Studio, the Process Server service on your PC runs at the localhost address. If you have trouble deploying to local-host, you can try restarting that service. To restart, right-click on My Computer, and select Manage; double-click on Services and Applications, double-click on Services, scroll down to the Verastream Process Server service, right click on it, and choose Restart.

Deployment means packaging up the project you have been workingonandsendingthefilesneededtorunittotheserver.The server includes a runtime which interprets and executes the code,takingactionsthatthecodespecifies.

1. From the File menu, select Deploy to Process Server....

2. Enter the server address of your process server, then click OK. By default, the server address is localhost.

3. If prompted, enter the username and password for the server. The defaults are:

username: admin password: secret

4. In the Deployment Succeeded dialog box, click Test Service to launch the Web Services Explorer.

When the deployment is complete, you see a dialog with a URL called the ‘Service WSDL’. Always make note of this URL: this is how you access your BPEL process.

NOTE: Don’t dismiss the ‘Deployment Succeeded’ dialog yet! You’ll use it in the next step. (If you’ve already dismissed it, you can deploy again.)

Your deployment is successful!

Deploying the POST process

9

If you have already dis-missed the Deployment Succeeded dialog, you can redeploy. Alternately, File > Launch Web Services Explorer... will connect to the last deployed Web service.

The next step is to test whether the POST process works as you expect. The process should return a shortened URL from the lengthy input URL. We’ve just deployed it, let’s execute it.

TofinishtestingyourdeploymentfrominsidetheProcessDesigner:

1. On the Deployment Succeeded dialog, click Test Service to open the Web Services Explorer in your default Web browser.

2. Enter an input string. In this example we used the very long URL:

http://docs2.attachmate.com/verastream/vpd/r5sp1/en/index.jsp?topic=%2Fcom.attachmate.eclipse.compositeservices.bpel.designer.help.online%2Fgettingstarted%2Fpd_intro.xhtml

3. CopytheURLintotheInputStringfieldandclickGo.

4. TheprocessresponsedisplaysintheStatusfield.Itshouldlook like this ( Of course the last part of your URL will be different): ‘Output (string): http://goo.gl/JLIBf7.

Congratulations! The URL was successfully shortened. We can now use the RESTful service and the GET method to retrieve the long URL from the output of the process.

Testing the POST process

10

To complete the tutorial, you will create a new project, using the GET method, that will input the short URL (returned by the POST process you just created) and return the original long URL.

To do this you will follow a number of steps you completed in the POST project, including creating a new project, deploying, and testing.

1. Open the New Project dialog box. (File > New Project).

2. Name the project Restful_GET.

3. In the BPEL Editor, delete the DoSomethingHere template and drag the RESTful extension activity between the ReceiveInput and the ReplyWithOutput activities.

Creating the RESTful GET project

You will again use the path to the RESTful service that Google provides:

https://www.googleapis.com/urlshortener/v1/url.

It is important to be familiar with the API docu-mentation provided by the RESTful service before you create a process in the Process Designer.

11

Setting the GET project properties

1. With the RESTful extension activity selected, open the Properties panel.

2. Set the Request method to GET.

3. Enter the path to the same RESTful service that you used in the POST project:

https://www.googleapis.com/urlshortener/v1/url

4. To add the name of the parameter that will be passed into the VPD service, in the Parameter section, Name field,typeshortURL. The name is available from the API documentation.

5. With the Value fieldselected,clicktheExpressionEditoricon to open the Expression Editor. The value parameter is assigned using the Expression Editor and is the shortened URL that was returned by the POST service.

6. In the Expression Editor select payload.request. The payload.request is used to pass in the shortened URL.

7. Click OK to close the Expression Editor and add the value to the Parameters property.

8. Request.payloadisinsertedintotheValuefieldoftheProperties panel.

Parameters are similar to properties. Information

about the parameter name value pair is avail-

able in the RESTful API documentation.

12

Assigning the response

Just as you did previously, you need to assign the response from the RESTful service to the output of the VPD service.

1. In the BPEL Editor, add an Assign activity to the process between the RESTful and ReplyWithOutput activities and name it AssignLongURL.

2. With AssignLongURL selected, open the Properties panel and click to open the Copy Rule dialog box.

3. Create an expression that will assign the response to the processoutput.The‘longURL’elementisspecifiedintheAPI documentation.

4. Click OK. Your GET project is complete. The next step is to deploy and test your GET project.

13

Deploying and testing

To deploy and test your GET project, follow the same steps as you did when you deployed the POST project.

1. From the File menu, select Deploy to Process Server....

2. Enter the server address of your process server, then click OK. Defaults are: address: localhost username: admin password: secret

3. In the Deployment Succeeded dialog box, click Test Service to launch Web Services Explorer.

4. In Web Services Explorer, enter the shortened URL response from the POST service and click Go.

5. IntheBodyfield,theoriginallongURLshouldbereturned.

http://docs2.attachmate.com/verastream/vpd/r5sp1/en/index.jsp?topic=/com.attachmate.eclipse.compositeservices.bpel.designer.help.online/get-tingstarted/pd_intro.xhtml

You’ve successfully completed the RESTful services tutorial. Given a knowledge of the RESTful service you want to invoke, you can easily incorporate these services into your business processes.