You are viewing the documentation for Blueriq 15. Documentation for other versions is available in our documentation directory.
Tags | Webservice, REST |
Type of accelerator | Example project to demonstrate Blueriq functionality and accelerate your learning journey. |
How to get | |
Compatibility | Blueriq 12.13 and higher |
Description
This model shows how error handling can be modeled in Blueriq as a Rest service (BAARS).
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 (example below). Blueriq only supports single-valued numeric status codes between 2xx and 5xx. If something else is mapped, the BAARS will throw a 500 message. Mind the capital letter S in Status since the header name is case sensitive.
Types of validations / errors
Input validation
Input validation is done on the received request. Input validations can be modeled on the domain schema of the request (example below).
For the AQ_RestServiceClient, no validation is performed on the response.
Parsing and validating the request
For REST services based on Domain Schemas, the request is parsed, mapped in the profile and the elements (attributes and relations) are validated. This means that when the validation starts, the profile is complete, so elements from fragments, arguments, headers and request body that depend on each other can also be validated.
For REST services based on XSD schemas, validations are performed on the fly, as the message is being parsed. This means that when the validation of an element starts, the validation rules on that element might depend on other attributes and relations which have not been parsed yet, and whose values at that point are unknown.
Basic input validation
By default, validation messages are returned in a single string error message, concatenated with new lines characters. This validation mode is available for both XSD based and Domain Schema based REST services.
Extended input validation
For REST services based on Domain Schemas, input validation can be set to return an extended response in the form of a validation tree of the whole request domain. The validation tree contains four sections: arguments
, body
, fragments
and headers
. In this way, it is easier to identify the instance on which a validation error occurred. By default, this behavior is disabled. For more details on how to enable this functionality, please check the documentation here.
Constructing the structured validation response
Values returned in the validation messages are from the profile and not directly from the initial request. By being returned from the profile, it means that value formatting applies to the values that are present in the validation message, like in the example below. Please note the number and percentage values from the request and from the response with validation message.
Other considerations on input validation
- Having null values in an array: see point 1 Know Issues Section
- Validating duplicate values: see point 2 in Know Issues Section
- When calling a BAARS from an AQ_RestServiceClient, please note the fact that the client does not validate responses.
Model validation
More complex validations can be handled in the model, using the HTTP status code combined with self created error codes and error messages (example below).
Errors
The BAARS will throw an 500 message in case of an unexpected error. In the case of the example this is when one or both input parameters are unknown. This should be handled by another model validation so this can not happen in a production environment.
Example project
Input validation
Model validation
Errors
Known issues in input validation
- When sending a JSON array which contains a null value, the Runtime fails with a 500 Internal Server Error, instead of a 400 Bad Request and some information about what was wrong. This problem is reproducible when using a Rest Service with a domain schema with hidden root.
- When structured schema validation is used, there are validation errors on the input and the request contained an array with duplicate values, then the part of the structured validation response corresponding to the array with duplicate values will not show the duplicates. This is because values from the validation message are being returned from the profile, and not from the initial request and in Blueriq, multi-valued attributes cannot have duplicates.