You are viewing the documentation for Blueriq 15. Documentation for other versions is available in our documentation directory.

Table of contents

 

What is it for?

The REST service editor is used for setting up request and response parts of a REST service. This can be used for calling external REST services or for setting up Web services Blueriq as a Service BaaS.

You can find the REST service editor under Connectivity.

Unlike a Schema set, or a SOAP Service, you have to create a REST service object yourself. 

A REST service has the following structure:

  • Service
    • Operation
      • request
      • response
    • Operation
      • request
      • response

    • ...

Within REST there are four operations available; PUT, POST, GET, DELETE.

Create REST service

After creating a REST service click on the root item of the tree and you will see the screen shown below. 

  1. This is the location of the server. You do not need to provide the full path here. You can add fragments and arguments later on.
    • If you are creating your own web service, no location is necessary
  2. Here you must specify the XSD schema set or the Domain schema that you want to use for sending and receiving data. 

Operations

Add an operation by clicking on the + and select the newly created operation. Give it a name, for example:

In the operation editor screen, you can provide documentation that will be part of the service's Swagger feed.

Request

When calling an external REST service, this part defines the request you send to the service.

When setting up a web service (BaaS), this part defines the format for incoming requests.



  1. Select a singleton entity in which you store data concerning your request (for BaaS: the entity in which the request data format is modeled).
  2. This is the composed target URL which will be called. This URL consists of location, fragments and arguments. The target is the actual request.
  3. Fragments are part of your URL. Constant fragments never change.
  4. Dynamic fragments are determined during runtime. Select an attribute from the request entity (1) which will be read.
  5. Arguments are similar to fragments, with the difference that they consist of 2 parts. Example: format = xml
  6. Here the operation type is specified. Choose between PUT, POST, GET and DELETE.
  7. Here the message header can be specified. The headers must be attributes from the request entity.

For domain schemas

  • Some services need a request header, for instance the header Accept that specifies the type of response. 
  • For parsing a message Blueriq supports application/json and application/xml out of the box. The headers can be multivalued.
  • Another header type is the Content-Type. The Content-Type specifies the message format and is not multivalued. If the Content-Type is not set, then the default is application/json.

For XSD schema set

  • By default the message format is XML. Therefore Accept headers and Content-Type headers are set automatically.

If you choose PUT, POST or DELETE then you need to specify the request as well. See the description at Response.


Dynamic arguments

When adding a dynamic argument, it is possible to add validation rules and set if the argument is required or not. By default dynamic arguments are required. When the argument is not required, it can be left out of the url when calling the webservice.

Response

The following paragraph describes the configuration of the response, this is split into XSD schema set and domain schema.

When calling an external REST service, this part defines the message you (expect to) receive from the service.

When setting up a web service (BaaS), this part defines the response Blueriq will give to an incoming request.

XSD Schema Set

The image below is an example of response when using an XSD Schema Set. 

  1. The entity that is the singleton where you start capturing the response.
  2. Define the headers of your message using attributes of the response instance.
  3. You can select an entity as body element. This is the entity that captures the actual content of the response.
  4. The schema element can be added when you want to receive data that is not part of your profile, for example the justification tree.
  5. This is the 1:1 relation between the entity in (1) and the entity in (3).
  6. Here you can add validations for the response.
     
  • The validations can only be validation types. It is not possible to use validation rules.
  • The Body relation is only shown when the body element has a value. It can switch to Body attribute when you only want to receive an attribute without selecting a body element. You want this if the response consist only of a single value without any representation of a structure.

Domain schema

When using a domain schema the response configuration of the body looks like the image below. Only the part that differs from XSD schema set is shown.
  1. Select the domain schema that you want to use for the response.
  2. Select the 1:1 relation from the response singleton to the domain entity that links to the content of the response.



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