Stricter validation coming soon in the REST API

[Updated 10-05-18]

On November 1, 2018, we will begin to validate request payloads more strictly. The change will affect all POST, PUT, PATCH, and DELETE endpoints in the REST API. Because of the strict validation changes outlined in this document, calls that currently return a 2xx success code may return a 422 Unprocessable Entity.

Please note that any documented irregularities will continue to be respected.

Before turning stricter validation on for an endpoint, we've been running an experiment using github/scientist. This alerts us to payloads that would have been invalid, allowing us to investigate why the payload would have failed. When we see a large number of errors, we've been reaching out to affected integrators and client library authors individually.

Here's what will change

While some validation in the API is already strict, lenient validation will be tightened up in the following ways:

Undocumented request body parameters will no longer be accepted. Currently, if you pass a parameter named rainbow to an endpoint that accepts only state, the API will typically ignore it. The strict validation will reject this with an error telling you that rainbow is not a valid parameter.

Strict validation only applies to parameters passed as part of the request body, and not to query parameters.

Types will be checked. Currently, if you pass the value "12" for a parameter documented as an integer, we will often coerce the value to an integer and move on. The strict validation will reject this with an error telling you that "12" is not an integer.

The same goes for other types. For example, booleans must be true or false, not the strings "true" or "false", or integers 1 or 0 or strings "1" or "0".

Enums will be case sensitive. Occasionally, we currently accept case-insensitive values where the documentation specifies a small set of exact strings. If you pass a value "GREEN" for a parameter that is documented as allowing "green" or "red", the strict validation will reject it with an error telling you that "GREEN" is not one of "green" or "red".

Optional parameters will not be nullable. You can no longer pass an optional parameter with the value null. This is perhaps the trickiest strict validation change. Currently, when the documentation specifies that the optional parameter "description" is a string, the API will typically accept "description": null. It will process this as though you did not pass the "description" parameter at all.

With the strict validation, you can either pass a valid parameter, or not pass it at all. Passing the optional string parameter "task" with a value of null will be rejected with an error that tells you that for 'properties/task', nil is not a string.

Redundant mark as read parameters will be removed.

The "mark notification(s) as read" endpoints (listed below) have long accepted an undocumented value "read" which could only ever be true. Using the following endpoints will mark notifications as read, so this redundant parameter will no longer be accepted.

If you have any questions please reach out!