Validate API Specification
Validating API specifications is essential to ensure that the API behaves as expected, maintains data integrity, effectively handles errors, enforces policies, and provides security. API Validation acts as a gatekeeper to maintain the quality and security of the API services. API Gateway provides capability to validate API specifications that provides answers to the following concerns you might have:
1. How can I ensure that the API consistently meets the defined schema and regulations?
2. What measures must you take to prevent the API from processing incorrect or malformed data?
3. How do I manage errors that occur during API interactions?
API Gateway provides the request processing and response processing policies that can be used to validate the incoming request or an outgoing response against API's various specifications such as schema, query parameters, path parameters, cookie parameters, content-types, and HTTP Headers referenced in their corresponding formats.
In this example, let’s see how to use the capabilities of API Gateway to validate API specifications for an incoming request by enforcing the Request processing policy by configuring the four policy properties, namely, Schema, HTTP Headers, Path parameters and Query Parameters to the REST API online_petstore.
Before you begin:
Ensure that the online_petstore API is activated.
To enable Validate API specification policy
1. Log on to API Gateway.
2. Click APIs on the navigation bar.
3. Select online_petstore API.
4. Click Edit.
5. Click Policies.
6. Select Request Processing > Validate API Specification.
7. Click Save.
The validate API specification policy is enforced.
8. Enable the following policy parameters to validate the API against the set specifications.
To validate the API against
Schema1. Click Policies > Edit.
2. Select Schema under policy parameters.
3. Click Save.
4. Click API Details > Resources and methods.
5. Expand /getTimeAfterJson/{time} and make a note of the inline schema.
6. Open Postman.
7. Provide the value {"latitude":1, "longitude":27} under the Body section.
8. Select the HTTP method as POST.
9. Invoke the endpoint http://host:port/gateway/online_petstore/0.1.9/getTimeAfterJson/100
10. Click Send.
The online_petstore API is invoked and returns a response since the value provided aligns within the bounds of the inline schema.
If you provide an empty value or a value which does not adhere to the inline schema, the validation fails, and an error with the status code 400 is displayed.
To validate the API against
HTTP HeadersHTTP headers are essential communication channel between clients and API Gateway, enabling the customization of requests and responses. Validating HTTP headers ensures security, data integrity and effective routing.
1. Click Policies > Edit.
2. Select HTTP Headers under policy parameters.
3. Click Save.
4. Click API Details > Resources and methods.
5. Expand /test-header-boolean.
Note that the data type of the selected REST resource is boolean, that is, the value must be either true or false.
6. Open Postman.
7. Select Headers.
8. Set the value of test-header-boolean as true.
9. Select the HTTP method as POST.
10. Invoke the endpoint http://host:port/gateway/online_petstore/1.0/test-header-boolean
The online_petstore API is invoked and returns a 200 OK status code.
If you provide a data type other than
boolean, the validation fails, and an error with the status code 400 is displayed.
To validate the API against
Path ParametersIn API Gateway, a path parameter is a dynamic value extracted from the segmented paths in the HTTP request. You can configure the API request path using the format - /path/{parameter}. This allows API Gateway to match the path in an HTTP request based on your configured parameter path. Validating the path parameters prevents unauthorized access and ensures accurate routing of the requests.
1. Click Policies > Edit.
2. Select Path Parameters under policy parameters.
3. Click Save.
4. Click API Details > Resources and methods.
5. Expand /integerPathParam/{intParam}.
Note that the Type of the selected REST resource is Path and Data type is Integer.
6. Open Postman.
7. Select the HTTP method as POST.
8. Invoke the endpoint http://host:port/gateway/online_petstore/1.0/IntegerPathParam/123
The endpoint is appended with the value 123, and the online_petstore API is invoked, returning a 200 OK status code.
If you provide a data type other than integer, say string http://host:port/gateway/online_petstore/1.0/IntegerPathParam/abc, the validation fails, and an error with the status code 400 is displayed.
To validate the API against
Query ParametersQuery Parameters are key-value pairs that appear after the ? (question mark) in the endpoint URL. Validating these query parameters is necessary for security and reliability. It ensures that the incoming requests conform to the expected formats, reducing the risk of vulnerabilities and security threats.
1. Click Policies > Edit.
2. Select Query Parameters under policy parameters.
3. Click Save.
4. Click API Details > Resources and methods.
5. Expand /stringQueryParam.
Note that the Name of the selected REST resource is queryString, Type is Query and Data type is String.
6. Open Postman.
7. Select the HTTP method as POST.
8. Invoke the endpoint http://host:port/gateway/online_petstore/1.0/stringQueryParam?queryString=abc
The name querystring is appended to the endpoint with a tring value, and the online_petstore API is invoked, returning a 200 OK status code.
Note:
When validating a query parameter in an endpoint you want to invoke, always prefix it with a ?.
If you provide a Name other than queryString in the endpoint, for example, http://host:port/gateway/online_petstore/1.0/stringQueryParam?name=abc, the validation fails and you see an error with the status code 400.
