You are viewing the documentation for Blueriq 17. Documentation for other versions is available in our documentation directory.
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;
| Value | Description |
|---|---|
| Both | This 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) |
| Outgoing | Indicates 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).
| # | Property | Description |
|---|---|---|
| 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). |
| 2 | HTTP method | Here the operation type is specified. Choose between |
| 3 | Example 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.
| # | Property | Description |
|---|---|---|
| 4 | Type | Specifies the type of fragment. Choose between Constant and Dynamic. |
| 5 | Value (Constant fragment) | Fill in a value. Constant fragments never change. |
| 6 | Value (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 ( |
Arguments
Arguments are similar to fragments, with the difference that they consist of 2 parts.
| # | Property | Description |
|---|---|---|
| 7 | Name | Name of the argument. |
| 8 | Type | Specifies the type of argument. Choose between Constant and Dynamic. |
| 9 | Value (Constant argument) | Fill in a value. Constant arguments never change. |
| 10 | Value (Dynamic argument) | For dynamic arguments, it is possible to add validation types ( |
Headers
HTTP headers let the client and the server pass additional information with an HTTP request or response.
| # | Property | Description |
|---|---|---|
| 11 | Name | Name of the header. |
| 12 | Value | The 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/jsonandapplication/xmlout of the box. The headers can be multivalued.- Derived XML or JSON media types (e.g.
application/hal+json) are also supported.
- Derived XML or JSON media types (e.g.
- 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.
| # | Property | Description |
|---|---|---|
13 | Domain schema | Select the schema which defines the structure of the message. |
| 14 | Request entity | The 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). |
| 15 | Request body relation | This is the 1:1 relation that connects the request entity (1) with the root entity of the selected domain schema (13) |
| 16 | Domain schema root entity | This 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.
| # | Property | Description |
|---|---|---|
| 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.
| # | Property | Description |
|---|---|---|
| 2 | Name | Name of the header. |
| 3 | Value | The 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.
| # | Property | Description |
|---|---|---|
4 | Domain schema | Select the schema which defines the structure of the message. |
| 5 | Response entity | The 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). |
| 6 | Request body relation | This is the 1:1 relation that connects the response entity (1) with the root entity of the selected domain schema (4) |
| 7 | Domain schema root entity | This 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). |
Overview
Content Tools