This AIP is currently under review. This means that the editors have read it and are in high-level concurrence, and while it is not yet fully approved, we have a good faith expectation that the AIP will be approved in something close to its current state.

AIP-163

Validating changes

Occasionally, a user wants to validate an intended change to see what the result will be before actually making the change. For example, a request to provision new servers in a fleet will have an impact on the overall fleet size and cost, and could potentially have unexpected downstream effects.

Guidance

APIs may provide an option to validate, but not actually execute, a request, and provide the output that it would have provided if the request was actually executed.

To provide this option, the method should include a bool validate_only field in the request message:

message ReviewBookRequest {
  string name = 1 [(google.api.resource_reference) = {
    type: "library-example.googleapis.com/Book"
  }];
  int32 rating = 2;
  string comment = 3;

  // If set, validate the request and preview the review, but do not actually
  // post it.
  bool validate_only = 4;
}

The API must perform permission checks and any other validation that would be performed on a “live” request; a request using validate_only must fail if the actual request would fail for any reason.

Note: It may occasionally be infeasible to provide the full output. For example, if creating a resource would create an auto-generated ID, it does not make sense to do this on validation. APIs should omit such fields on validation requests in this situation.