Skip to content

OAS: Validation and Processing of Requests and Responses

Jump to bottom
Julian-Mueller-GIP edited this page Oct 21, 2024 · 3 revisions

Generated OAS applications provide basic functionality to automatically validate requests and responses. By default, validation is active for all generated applications and can be disabled by setting the xyna propery xmcp.oas.validation.default to false. Additionally, pre- and post-processing of requests and responses can be added in both client and provider applications. It is possible to customize validation and processing by overriding dedicated services of the OAS Base Application.

Provider applications

In provider applications, the endpoints of the api are contained as services in api data types, grouped by the tags defined in the specification file. All api data types inherit the services from the base datatype xmcp.oas.datatype.OASBaseApi for custom pre- and post-processing and to control validation.

oas_base_api

Validate during Decode and Validate during Encode

Theses Services are used to enable or disable the Validation for requests (decode) and responses (encode). The default implementation for both services reads the xyna property xmcp.oas.validation.default and returns its value. By overriding one of the services, you can decide if the request or the response of an individual endpoint should be validated. The services receive the request or response parameter of the respective endpoint as input, which can be used to distinguish between the endpoints.

Build Respose after Error and Build Response after Error during Encode

With theses services you can define the HTTP responses that will be send to the client, after an error occurred during the json parsing or validation. In the default implementation both services call the workflow xmcp.oas.exception.BuildResposeAfterError, which returns different responses for exceptions caused by json parsing, validation and other exceptions. The defined error responses are used for all endpoints in the same api data type.

Preprocess Request and Postprocess Response

In these services you can implement any additional processing of requests and responses that is necessary for your api. There is no pre- and post-processing by default, the request and response parameters are passed through unchanged. Like before, custom processing added here is executed for all endpoints in the same api data type.

Client applications

The request workflows for the endpoints in a client application are not grouped in any way and are practically independent of one another. A client application contains two request workflows for each endpoint, one with the extension "with Processing" in its name and one without. The workflows without the name extension use the default validation and processing. The "with Processing" workflows, receive an additional hook datatype xmcp.oas.datatype.client.ClientProcessingHook as input, which contains the services to customize validation and processing. You can create any number of derived client processing hooks with one or more overridden services and pass them to the request workflows as required.

client_processing_hook

Validate Send Parameter and Validate Response

The two services have the same function as Validate during Decode and Validate during Encode in the provider application. They read the property xmcp.oas.validation.default by default and returns its value. Override these services to decide if the request or the response should be validated in the request workflow.

Preprocess Request and Postprocess Response

As in the provider application, you can implement all the necessary additional processing of requests and responses here. Again, there is no pre- and post-processing by default, the inputs are passed through unchanged.

Validation

Supported String Formats

The generated OAS applications support automatic validation of the string formats listed below. The format names, as well as possible hexadecimal values are treated as case-insensitive.

  • uuid: 128 bit number as hexadecimal value in the 8-4-4-4-12 format, e.g. 3d7e3fae-24b3-4e77-9b88-0b5b366499b3
  • mac and macaddress: Both names are equivalent. A 48 bit address in hexadecimal format, where the bytes may be separated by dashes or colons.
    Examples for valid mac addresses are 01ab23cd45ef, 01:ab:23:cd:45:ef, 01-ab-23-cd-45-ef, 01ab23-cd45ef.
  • ipv4: 32 bit IPv4 address in dot-decimal notation, e.g. 192.168.1.0
  • ipv4prefix: IPv4 address with added network prefix in CIDR notation, e.g. 192.168.1.0/24
  • ipv4netmask: IPv4 subnet mask in dot-decimal notation, e.g. 255.255.255.0
  • ipv6: 128 bit IPv6 address as hexadecimal value separated by colons, e.g. 2001:0db8:85a3:08d3:1319:8a2e:0370:7347
    One or more groups of 16 bits of zeros can be shortened with "::", so 2001:0db8:85a3:0000:0000:8a2e:0370:7334 reduces to 2001:0db8:85a3::8a2e:0370:7334. Double colons may only appear once per address. With this notation the loopback address and the unspecified address reduce to ::1 and ::, respectively.
  • ipv6prefix: IPv6 address with added network prefix in CIDR notation, e.g. 2001:0db8:85a3:08d3:1319:8a2e:0370:7347/64.
    Note, that the special prefix ::/0 (default route) is also valid.
Clone this wiki locally