Validate API Specification
This policy validates the incoming request against API's various specifications such as schema, query parameters, path parameters, content-types, and HTTP Headers referenced in their corresponding formats as follows:
![*](chapterTOC_bullet.png)
The schema is available as part of the API definition. The schema for SOAP API are imported through WSDL and for REST APIs it can be through swagger, RAML or can be uploaded by the user.
![*](chapterTOC_bullet.png)
The query parameters, path parameters and content- types are available as part of the API definition.
![*](chapterTOC_bullet.png)
The HTTP Headers are specified in the Validate API Specification policy page
The request sent to the API by an application must conform with the structure or format expected by the API. The incoming requests are validated against the API specifications in this policy to conform to the structure or format expected by the API.
Various API specifications validated are:
Schema: The incoming requests are validated against the schema provided in the API definition. The schema defines the elements and attributes and specifies the data types of these elements to ensure that only appropriate data is allowed through to the API.
For a REST API, the schema can be added inline or uploaded in the Technical Information section on the API Details page. The validation depends on the Content-type header in the request or Accept header in the response and the corresponding schema validation would be executed. The default Content type/Accept header and schema validation type mapping is as follows:
Content-type/Accept | Schema validation type |
application/json application/json/badgerfish | JSON schema |
application/xml text/xml text/html | XML schema |
text/plain | Regex schema |
For a SOAP API, the WSDL and the referenced schema must be provided in a zip format. The JSON schema validation is supported for the operations that are exposed as REST.
Note:
If schema mapping is not found for a content-type of the request in the API, the behavior is as follows:
![*](chapterTOC_bullet.png)
If schema mapping is not available in a REST API or SOAP-to-REST transformed API, the validation is skipped.
![*](chapterTOC_bullet.png)
If application/json is mapped to XML schema in the API definition, then the JSON content in the request is validated against XML schema to provide a backward compatibility support for APIs migrated from the 10.1 version.
![*](chapterTOC_bullet.png)
If only XML schema mappings exist for any of the content-types, the payload is converted into XML and validated against all the XML schemas. If the payload is valid against one of the schemas, the validation is successful.
![*](chapterTOC_bullet.png)
If the payload is not XML convertible, the validation is not performed and the request is allowed to reach the native API.
Query Parameters:This is applicable only for a REST API. The incoming requests are validated against the query parameters specified in the API definition.
Path Parameters:This is applicable only for a REST API. The incoming requests are validated against the path parameters specified in the API definition.
Content-types:The incoming requests are validated against the content-types specified in the API definition.
Note:
When Content-type validation is selected for a SOAP API, the validation fails in case of SOAP to REST scenarios and displays an error with 500 status code instead of 400 as displayed in the other scenarios.
when we have Content type validation selected for SOAP API,when SOAP TO REST scenarios , this validation will not happen i.e An error will be thrown wi h 500 status code and not 400 as the other scenarios
HTTP Headers:The incoming requests are validated against the HTTP Headers specified in this policy to conform to the HTTP headers expected by the API.
The runtime invocations that fail the specification validation are considered as policy violations. You can view such policy violation events in the dashboard.
The table lists the API specification properties, you can specify for this policy, to be validated:
Parameter | Description |
Schema | Validates the request payload against the appropriate schema (based on the Content-type header in request or Accept header in response). Provide the following additional features for XML schema validation: Feature name. Specifies the name of the feature for XML parsing when performing XML schema validation. Select the required feature name from the list: GENERATE_SYNTHETIC_ANNOTATIONS ID_IDREF_CHECKING IDENTITY_CONSTRAINT_CHECKING IGNORE_XSL_TYPE NAMESPACE_GROWTH NORMALIZE_DATA ROOT_ELEMENT_DECL ROOT_TYPE_DEF SIGMA_AUGMENT_PSVI SCHEMA_DV_FACTORY SCHEMA_ELEMENT_DEFAULT SCHEMA_LOCATION SCHEMA_NONS_LOCATION SCHEMA_VALIDATOR TOLERATE_DUPLICATES ENPARSED_ENTITY_CHECKING VALIDATE_ANNOTATIONS XML_SCHEMA_FULL_CHECKING XMLSCHEMA_VALIDATION Feature value. Specifies whether the feature value is True or False. |
Query Parameters | This is applicable only for REST APIs. Validates the query parameters in the incoming request against the query parameters defined in that request's API Specification. The configuration is provided in the API details page. |
Path Parameters | This is applicable only for REST APIs. Validates the path parameters in the incoming request against the path parameters defined in that request's API Specification. The configuration is provided in the API details page. API Gateway supports the following data type formats: Data type | Format | integer | int32 signed 32 bits | integer | int64 signed 64 bits | number | float | number | double | string | | string | byte | string | binary | boolean | | string | date | string | date-time | string | password |
|
Content-types | Validates the content-types in the incoming request against the content-types defined in that request's API Specification. The configuration is provided in the API details page. |
HTTP Headers | Validates the HTTP header parameters in the incoming request against the HTTP headers defined in that request's API Specification. The configuration is provided in the API details page. Provide the following information: Condition. Specifies the logical operator to use to validate multiple HTTP headers in the incoming API requests. Available values are: AND. API Gateway accepts only the requests that contain all configured HTTP headers. OR. This is selected by default. API Gateway accepts requests that contain at least one configured HTTP header. HTTP Header Key. Specifies a key that must be passed through the HTTP header of the incoming API requests. Header Value. Optional. Specifies the corresponding key value that could be passed through the HTTP header of the incoming API requests. The Header Value field type accepts string and regular expression (regex). You can add more HTTP headers by clicking ![](../yai-webhelp/images/add.png) . |