This page describes the steps for calling a web service using the REST protocol. This page also gives you background information on how web services work within the Blueriq architecture. There are two possibilities in Blueriq to define the data that is sent to and from REST services. The first possibility is by using an XSD, and this works similar to calling a SOAP service, as described in 4. Calling a SOAP service. The second possibility is to define a domain schema.

The following steps have to be taken, you can choose between two different first steps (XSD or Domain schema):

1. Using an XSD

This method can only be used for communicating with web services that accept and send XML requests. If a different format such as JSON is required, you should use a domain schema.

Importing

In order to interpret an XML response from a REST web service, Blueriq needs to import an XSD. In contrast to SOAP, there may not be an explicit contract available for REST. You can use the API of the REST service to get XSD files.

If the REST service only gives example answers, you can generate an XSD file from the examples (see for instance http://www.freeformatter.com/xsd-generator.html).

To import an XSD file:

  1. Make sure that the XSD is supported. You can check that on the Web Services datasheet.
  2. In Blueriq Encore, select the branch level in the navigation panel → 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), provide a ZIP file with all files needed. 
  3. Select the project for the import and you can choose whether to create a new module, or overwrite an existing one.
  4. The option 'Generate Domain' will automatically generate a domain model for you, based on the XSD schema. When this button is checked, entities, attributes and relations are created based on the type definitions in the XSD. When using an existing module, there may already be a domain model present, that uses identical names as in the XSD. When overwriting, conflicting elements are not created. Obviously, these problems do not occur if you use a new module. When 'Generate Domain' is unchecked, no domain model is generated for you. In that case, you can later map the elements from the XSD to your own domain (explained later). In general, it is advised to use a separate module in order not to mix the domain model for the web service with the domain of your business.
  5. Now press the "Import" button and the XSD should be imported. 




Mapping with Domain Model

Open your project and go the module which contains the web service. The module now has a Schema Set. This item can be found in the navigation panel in the category named "Connectivity".

The Schema Set defines which entities, attributes and relations are used by the web service (they map the XSD to the domain model). This works exactly the same for REST and SOAP, and the description can be found here: 4. Calling a SOAP service.

2. Using a domain schema

The domain schema lets you define a representation of the elements in the application, and that is used for the communication with a web service. The purpose of this representation is to define what items are needed to accurately describe an element (for example the representation of person is his first name, followed by his second name.). You can see the domain schema as a sort of contract of the communication. You start with an entity that represents the begin and the end of the message. For every attribute/relation you can select a name, what datatype it is, if it is required within the message and if it is multivalued. This contract should be set up to reflect the message that is sent, but it can be different to the internal Blueriq domain. For instance, your contract uses a multivalued attribute. Your application always has one value for this attribute however, so it is not multivalued. When sending a message, it is no problem to insert a single-valued attribute in a multivalued entry in the domain schema. It will just be sent as a list with only one entry. You have to be careful if it is the other way around, storing a list with possibly more values on a single valued attribute will not work.

You might notice that the domain schema that you define is rather similar to the domain in Encore. This is certainly true. Situations when you deviate from this is when only a subset of information is needed (summaries), or if you have control attributes that are not interesting for the communication.

An important point to note is that the domain schema is independent of the language that is used for the communication, and projects can add implementations of any representation not covered out-of-the-box (out of the box we offer JSON and XML). Blueriq uses the domain schema that you define in Encore as basis to create a message to a web service or to read a message from a web service. Using the domain schema Blueriq generates a JSON or XML message in a straightforward way during runtime. To inspect the translation to JSON, click the "JSON preview" button in Encore. 

Beware of case sensitivity in the JSON or XML message.

In the example on the right, the status of an airport is represented by a certain set of attributes, starting with the delay.




3. Defining the REST service

In contrast to importing a WSDL, no service definition is automatically generated. You have to manually define how the REST service is called. This section explains how you can configure a REST service element in Encore that uses either an XSD or domain schema.

3.1 REST service properties

After creating a new REST service in Encore, you need to specify the properties of the REST service in the properties panel. 

  • The direction of a REST service indicates how this REST service will be used. In this example, we want to call a REST service, so we set the direction to "Outgoing." "Both" can also be used and can be convenient if both the calling and receiving applications are built in Blueriq and use a shared library.
  • The location is the base URL. You can already specify fragments and arguments here, but then you cannot change them later. For example, check https://soa.smext.faa.gov/asws/api/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 https://soa.smext.faa.gov/asws/ as location in this case. 
    • Beware that the location can be set in the REST service, service call, and application.properties, in which the location specified in the REST service is the lowest and application.properties is the highest in the hierarchy.
  • The communication type can either be a Domain schema, or an XSD schema set. You have to choose one XSD schema set here that has to include everything for the entire web service. In contrast, by choosing a domain schema, you will later choose what domain schema to use for every separate method.



3.2 Operations

You can specify as many operations as you need, by pressing on the "Add operation" button. Give every operation a unique name. After adding an operation, the request and response expansion panels will appear. 

3.3 Request

  1. Select a singleton entity in which you store data concerning your request, this is used for:
    1. Dynamic fragment attributes
    2. Dynamic argument attributes
    3. Header attributes
    4. The body relation to the root entity of the domain schema / schema set
  2. For outgoing REST calls, Blueriq support 5 different HTTP methods: GET, POST, PUT, DELETE, and PATCH. In our example, the web service works with the GET method. This method does not alter the state of the web service and just asks for information. 
  3. Here the URL is shown that will be called. Items within {} are dynamic and determined at runtime.
  4. You can add static fragments which are always the same.
  5. You can also add dynamic fragments which are filled by attributes of the request entity. 
  6. You can specify arguments of your request the same way.
  7. You can also send a message to the REST web service as part of the HTTP headers. Request headers are more often used with POST and PUT methods. This procedure is the same as for the response of the message that you find just below here.




Some web services work with optional fragments. There is currently no way of defining optional fragments in this screen. The solution is to create a fragment attribute that concatenates different fragments using an expression.

For example: Request.PostalCode + ISUNKNOWN("/" + Request.HouseNumber, "").

3.4 Response

Now you can specify the format of the response message. If you need to set headers, then you can do so at in the same way you set arguments or fragments for the request. For example, you can store the status header in the profile, so that you can show a different message to the end user depending on the status code (e.g., 'Try again later' when the web service had a time-out). How this could look like in Encore is shown in the screenshot below.

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 screen looks different depending on whether you send information using an XSD schema set or a domain schema.

3.4.1 XSD schema set

We explain the XSD schema set first. First choose which entity will be sent ("Body element"). Fill in the name of the relation between your singleton response entity and your data entity. (Custom Schema) Elements 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 (An example is a justification tree).

3.4.2 Domsin schema

When using a domain schema, then simply select the domain schema that you want to use to send information. Furthermore, you have to select a body relation. This is a relation between the singleton response entity of your message and the entity that is chosen as the root entity in your domain schema.

The Response Data entity represents your complete message, including headers. The data that is sent, called the body, starts with the entity chosen as root element in the domain schema. Therefore, there should be a relation between the entity representing the message, and the entity representing the body. This relation should be selected at Body Relation. The message entity should be singleton.

4. Creating a Service Call

In order to call a REST web service, you create a service call of type AQ_RestServiceClient the same way as for SOAP web services (4. Calling a SOAP service). 

For our example, the parameters of the service call look like this:

5. Using the Webservice

This is similar to SOAP (4. Calling a SOAP service).

 Usually you want to use a separate module for your web service. Read more about this in Chapter 7 - Modules and Datamapping

 Previous: 4. Calling a SOAP service

Next: 6. Setting up Blueriq as a web service

  • No labels

2 Comments

  1. Robert Lampe

    Using an XSD

    This method can only be used for communicating with web services that send XML responses.

    should be:

    This method can only be used for communicating with web services that accept and send XML requests.

    1. Unknown User (m.schadd)

      Agree, fixed.

Didn't find the answer you were looking for? Try the advanced search!