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

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 a Web service.

REST service elements can either be created manually, or imported from an OpenAPI definition.

A REST service has the following structure:

REST Service

The direction of a REST service indicates how this REST service will be used, it has the following options;

ValueDescription
BothThis is the default value, and indicates that the REST service can be used for both incoming and outgoing requests.

Incoming

Indicates that the REST service will only be used for a Web service (BaaS)
OutgoingIndicates that the REST service will only be used to call an external REST service


The default communication type of a new REST service is "Domain schema" (XML or JSON). It is possible to switch to "XSD schema set". This option is available in the properties panel. After doing so, a dropdown appears in which a schema set has to be chosen which will be available after importing an XSD

Operations

To add an operation to the REST service, select the "+ Add operation" button. You may add as many operations as you want, as long as the name of the operation is unique within the service. After adding an operation, the request and response expansion panels will appear. 

To delete or rename an operation, use the context menu (richt click on the operation or use the 3 dots: ).

To reorder the list of operations, you can use drag and drop. The order of operations does not affect the behavior in the runtime.

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.

The request consist of a general part, fragments, arguments, headers, and a body (in case of a HTTP method other than GET).

#PropertyDescription
1

Request data entity

Select a singleton entity in which you store data concerning your request (for BaaS: the entity in which the request data format is modeled).

2HTTP method

Here the operation type is specified. Choose between PUT, POST, GET, DELETE and PATCH.  Note that PATCH is only allowed when the direction of the REST service is set to 'Outgoing'.

3Example target URL

This is the composed target URL which will be called. This URL consists of location, fragments and arguments. The target is the actual request.

Fragments

Fragments are part of your URL.

#PropertyDescription
4TypeSpecifies the type of fragment. Choose between Constant and Dynamic.
5Value (Constant fragment)Fill in a value. Constant fragments never change.
6Value (Dynamic fragment)

Dynamic fragments are determined during runtime. Select an attribute from the request entity (1) which will be read. For dynamic fragments, it is possible to add validation types using the corresponding icon (). It is not possible to use validation rules.

Arguments 

Arguments are similar to fragments, with the difference that they consist of 2 parts.

#PropertyDescription
7NameName of the argument.
8TypeSpecifies the type of argument. Choose between Constant and Dynamic.
9Value (Constant argument)Fill in a value. Constant arguments never change.
10Value (Dynamic argument)

For dynamic arguments, it is possible to add validation types () and set if the argument is required or not (). When the argument is not required, it can be left out of the URL when calling the webservice. It is not possible to use validation rules.

Headers

HTTP headers let the client and the server pass additional information with an HTTP request or response.

#PropertyDescription
11NameName of the header.
12ValueThe headers must be attributes from the request entity (1).

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.

Body

The body is the actual message you want to send. When the HTTP method is GET, there is no body in the request part. 

#PropertyDescription

13

Domain schemaSelect the schema which defines the structure of the message. 
14Request entityThe request entity is equal to the selected request entity in (1). This field will be filled automatically and is here to provide more context for the relation in (15).
15Request body relationThis is the 1:1 relation that connects the request entity (1) with the root entity of the selected domain schema (13)
16Domain schema root entityThis is the root entity of the domain schema that is selected in (13). This field will be filled automatically and is here to provide context for the relation in (15).

Response

If you choose PUT, POST or DELETE then you need to specify the request as well. The following paragraph describes the configuration of the response. 

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.

#PropertyDescription
1

Response data entity

The entity that is the singleton where you start capturing the response.

Headers

HTTP headers let the client and the server pass additional information with an HTTP request or response.

#PropertyDescription
2NameName of the header.
3ValueThe headers must be attributes from the request entity (1).

HTTP Status code

The HTTP status code can be used in the model to handle errors. The HTTP status code is a header in the response and can be mapped to an attribute in the model. Blueriq only supports single-valued numeric status codes between 2xx and 5xx. If something else is mapped, the BAARS will throw a 500 message. The name of the header is: Status. Mind the capital letter S in Status since the header names are case sensitive.

Body

The body is the actual message you expect to receive. 

#PropertyDescription

4

Domain schemaSelect the schema which defines the structure of the message. 
5Response entityThe response entity is equal to the selected response entity in (1). This field will be filled automatically, is not editable, and provides context for the relation in (6).
6Request body relationThis is the 1:1 relation that connects the response entity (1) with the root entity of the selected domain schema (4)
7Domain schema root entityThis is the root entity of the domain schema that is selected in (4). This field will be filled automatically, is not editable and provides context for the relation in (6).