Schema validation checks each API request and response against the schemas you define in API builder. When validation is on, a request that doesn't match its schema gets an error and your API doesn't run. A response that doesn't match its schema gets an error too, so callers don't receive data in a shape you didn't intend. Use this article to turn on validation, set rules on fields, and understand what callers receive.
Prerequisites
- Edit permission on the API. Users with Monitor permission can't change the validation setting.
- A request or response schema. See Configure an API request using API builder and Configure an API response using API builder.
Turn on validation
Validation is one setting for the whole API. When it's on, API builder checks the request and every response against the schemas defined for this API.
To turn validation on, select Enable request/response validation in the Advanced section of API settings, and then select Save. For the full procedure, see Configure advanced API settings in Create and manage APIs using API builder.
Validation is off by default, including for new APIs. While it's off, API builder doesn't reject any request or response.
What validation checks
| Item | What validation checks |
|---|---|
| Request body | The body matches the schema in the API request. |
| Query parameters | Each query parameter marked Required is present and not empty. A value of only spaces counts as empty. |
| Response body | The body matches the schema in the API response that runs. |
Validation doesn't check headers, path parameters, or query parameters you haven't added to the API request. For a GET request, validation skips the body but still checks query parameters.
Set rules on a field
Each field in a request or response body has settings that depend on its type. To open them, select Additional settings on a field row. For how to add fields, see Configure an API request using API builder and Configure an API response using API builder.
| Field type | Settings |
|---|---|
| String | Description, Regex, Enum values, Min length, Max length, Required, Allow null |
| Number | Description, Enum values, Min value, Max value, Exclusive min, Exclusive max, Multiple of, Required, Allow null |
| Boolean | Description, Required, Allow null |
| Object | Description, Required, Allow null, and whether the object can contain fields you haven't defined |
| Array | The settings for the item type, plus Min items and Max items. Rules for the item type apply to each item. |
Rules behave as follows:
-
Required means the field is present. An empty string,
0,false, an empty array, and an empty object all pass. To reject an empty string, set Min length to 1. To reject an empty array, set Min items to 1. - Min length and Max length count characters, including spaces.
- Min value, Max value, Min length, Max length, Min items, and Max items include the number you enter.
- Exclusive min and Exclusive max take their own values and exclude the number you enter. If you set both Min value and Exclusive min, a number must pass both, so the stricter one applies. The same is true for Max value and Exclusive max.
- Multiple of must be greater than 0.
- To allow one exact value, use Enum values with a single value.
- API builder rejects combinations that can't work, such as a minimum above the maximum, a negative length, or an invalid regular expression. The field keeps its last saved settings.
- When you change a field's type, settings that no longer apply are cleared. When you remove a field, its settings are removed too.
What callers receive
| Result | When it happens | What the caller gets |
|---|---|---|
| HTTP 400 | The request body doesn't match its schema, or a Required query parameter is missing or empty. | An error that names the field and the rule it broke. Your API doesn't run. |
| HTTP 500 | The response doesn't match its schema. | A generic message. API builder doesn't send the response headers. |
| HTTP 501 | A saved schema has a rule that API builder can't run. Some regular expressions save but can't be run. | An error response. In a test run, you get HTTP 501 that names the schema location. |
Requests that validation rejects count toward your monthly API usage. If you've exceeded your usage limit, the caller gets HTTP 422 before validation runs.
For the error messages callers see and how to fix them, see Troubleshoot schema validation failures in Troubleshoot APIs. For the full list of error codes, see Error handling in API builder.
Limitations
- Validation applies to APIs built in API builder, not JavaScript APIs.
- Query parameters are checked for presence only. Validation doesn't check their type.
- Switching to Visual removes rules that Visual can't show. See Switch between Visual and JSON in Configure an API request using API builder.
- There's no Format control. A format that API builder infers from a sample file, such as
date-time, is kept and enforced. - If a step has already run when response validation fails, the caller gets HTTP 500 and the earlier steps aren't undone.
Best practices
- Turn validation on before you test. A test run doesn't report schema failures while validation is off. See Test and debug your API using API builder.
- If your API writes data, check how callers retry. A caller that gets HTTP 500 can send the request again.
- Mark only the query parameters callers must send as Required.