Dry Runs

A dry run is used to validate, without performing any changes, that the request does not contain any 4XX-level errors. Dry run options exist for API operations which have complex validation rules which are not suitable to be performed in the client.

For example, API requests that submit data from forms with multiple fields may use the dry run option. The API service performs the validation and enforces business rules rather than requiring the implementation of complex validation and business logic in the client. This helps keep the clients decoupled from the API service when business rules change.

Dry runs are not available for all API operations. To see if the dry run functionality is available, check the API reference documentation to see if the query parameter is listed under the API operation.   

Performing a Dry Run

To request a dry run, include the ?dryRun=true query parameter. If the dryRun query parameter is set to false or omitted, the request is processed as normal.

If an error does occur during a dry run, the response contains the normal error data and response code. Error codes typically include 400, 401, 403, 404, 412, 409, and 422 HTTP status codes. Error definitions and potential solutions are discussed in the API reference documentation for the operation.

If the request does not contain errors and passed validation, the response code is 204 -- No Content with no response body. Any task the request would complete beyond validation does not take place.

A successful dry run does not guarantee that the same request run without the dry run option will succeed without errors. Calls may still fail because other users may have changed the application state between the two requests, or the user’s authorization may have expired. Clients should be prepared to receive and handle 4XX-level responses, even if a dry run passed.