Chapter 5: Calling a REST service

In contrast to SOAP, there may not be an explicit contract available for REST (WADL). You can use the api of the REST service to get xsd files. If the REST service only gives example answers, you can automatically generate an XSD file from the examples. (http://www.freeformatter.com/xsd-generator.html#ad-output)

Go to File → Import → Import XSD and provide the location of the XSD file. If you have multiple files (for example: your XSD is importing/including an XSD schema) then provide a zip file with all needed files. Select the project for the import and you can choose whether to create a new module, or overwrite an existing one. When overwriting, as much as possible from the old module is kept. You can choose whether you also want to create a domain model. When this button is checked, entities, attributes and relations are created based on the type definitions of the XSD.

You should get the message that the import was successful.

Open your project and go the (newly-created) module which contains the webservice. The module now has a Schema Set. This item can be found in the bar on the left side of the screen, as can be seen below.

The Schema Set defines which entities, attributes and relations are used by the webservice (they map the XSD to the domain model). If the domain model was created automatically, then you can skip the following step, and directly go to Creating a Service Call.

Open the Schema Set, and unfold the schema. You can choose which entity is mapped to this type in XSD schema, as can be seen below. In this case, the anonymous complex type of the element “add” in the XSD schema is mapped to the entity “add” in the domain model (the red box).

When choosing simple elements, you can choose to which attributes they map. See below. Mapping relations works in a similar way.

For each operation, the webservice needs two singleton entities: a Request entity and a Response entity, which will be used to create the message. When you create the domain automatically, you will find these along with the other entities of the domain. You can use the soap service editor to create mappings for these, if you did not create the domain automatically, see below:

You have to define how the REST service is called manually. Create a new REST service object and give your REST service a name, see below:

Next, you need to specify the location of the REST service. This is an URI. You can already specify fragments and arguments here, but then you cannot change them later. For example, check http://services.faa.gov/airport/status/IAD?format=xml. In this case, airport, status and IAD are dynamic fragments and can change, depending on input by the user. You would only use http://services.faa.gov/ as location in this case.

Now specify the Schema Set that you want to use. Choose the Schema Set that you have imported earlier.

You can specify as many operations as you need, by pressing on the plus icon. Give every operation a unique name.

If you want to dynamically change the address or send custom headers or body in your message, you need to specify a singleton entity from where the information is gathered (1). (2) shows the URL you are going to call. Items within {} are dynamic and determined during runtime. You can add static fragments (3) which are always the same, or dynamic fragments (4) which are filled by attributes of the request entity. You can specify arguments (5) of your request the same way.

Now you can specify how your message looks like. (1) lets you specify what kind of message it is (Get, Post, Put or Delete). If you need to set headers, then you can do so at (2) in the same way you set arguments or fragments earlier. If you need to send information in the body of the message, for example with a Post message, then you can specify this now. This is done in XML, and your Schema needs to be able to handle this. If you have a SimpleType in the schema, then you fill in an attribute at (5). If it is a complexType, then first choose which entity will be send at (3) and then you attribute field (5) will swithc to a relation field. Fill in the name of the relation between your singleton request entity and your data entity. Custom Schema Elements (4) are ways to fill in your schema in a different way other than with data from your profile. It is not needed at the moment.

Now you need to define how you receive data from the REST service. Click on response and you will see a window just like the window in the screenshot above. Fill in the form the same way as explained above.

To call a webservice in studio, you need to create a service call. Chooses the AQ_WebServiceClient from the list of available service calls (do not forget to import the Blueriq library). Every operation in the WSDL needs its own service call.

Here you can define several attributes.

• Service Module: The module in which the service is located.
• Service: Select SOAP or REST service and select which service to call.
• Operation: This is the name of the operation which is going to be executed. You can look up the name in the WSDL.
• Url: For REST you need to leave this empty. If not, then you cannot use fragments or arguments defined in your service.
• Configuration Module: The name of the module where the datamapping is located. You need to specify this if your domain model is not in the same module as the webservice.
• Data Mapping: The name of the data mapping to be executed when this operation is called.
• Username: A possible username, for services with logins.
• Password A possible password, for services with logins.

After you have created your service call, you can use it inside a flow. The webservice throws a default event. When the service is executed, it will read the needed data from the domain model, starting from the singleton request instance. After receiving an answer from the server, the webservice will store the data in the domain model, starting from the singleton response instance. All data in these instances will be overwritten. If a data mapping is used, the mapping is executed after the domain module in the webservice module is filled. A common error is that an empty message is sent to the server. The reason for this is that the domain model for the webservice is not correctly initiated. If the webservice returns an error message, Blueriq runtime will show an error, because error messages are not supported yet.