feat: AIP-163 – Change validation

Author: Luke Sneeringer

aip/general/0163/aip.md.j2

@@ -0,0 +1,46 @@
+# Change validation
+
+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 same response (status code, headers, and response
+body) that it would have provided if the request was actually executed.
+
+To provide this option, the method **should** include a `validate_only` boolean
+field:
+
+```http
+POST /v1/publishers/{publisher}/books?validate_only=true HTTP/2
+Host: library.googleapis.com
+Accept: application/json
+```
+
+- Standard operations **must** expose the `validate_only` field on the query
+  string.
+- Custom operations **may** expose the `validate_only` field in the request
+  body, on the query string, or accept either one.
+
+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 it determines that the actual request would fail.
+
+**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.
+
+## Interface Definitions
+
+{% tab proto %}
+
+{% sample 'standard_operation.proto', 'message CreateBookRequest' %}
+
+- The `validate_only` field **must** use the `bool` type.
+- The `validate_only` field **must not** be annotated as `REQUIRED`.
+
+{% endtabs %}

aip/general/0163/aip.yaml

@@ -0,0 +1,7 @@
+---
+id: 163
+state: approved
+created: 2019-12-16
+placement:
+  category: design-patterns
+  order: 90

aip/general/0163/standard_operation.proto

@@ -0,0 +1,74 @@
+// Copyright 2020 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+
+service Library {
+  // Create a single book.
+  rpc CreateBook(CreateBookRequest) returns (Book) {
+    option (google.api.http) = {
+      post: "/v1/{parent=publishers/*}/books"
+      body: "book"
+    };
+    option (google.api.method_signature) = "parent,book";
+  }
+}
+
+
+// The request message for creating a book.
+message CreateBookRequest {
+  // The parent collection where this book will be created.
+  // Format: publishers/{publisher}
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "library.googleapis.com/Book"
+    }];
+
+  // The book to create.
+  Book book = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // If set, validate the request and preview the review, but do not actually
+  // post it.
+  bool validate_only = 3;
+}
+
+// A representation of a single book.
+message Book {
+  option (google.api.resource) = {
+    type: "library.googleapis.com/Book"
+    pattern: "publishers/{publisher}/books/{book}"
+  };
+
+  // The name of the book.
+  // Format: publishers/{publisher}/books/{book}
+  string name = 1;
+
+  // The ISBN (International Standard Book Number) for this book.
+  string isbn = 2;
+
+  // The title of the book.
+  string title = 3;
+
+  // The author or authors of the book.
+  repeated string authors = 4;
+
+  // The rating assigned to the book.
+  float rating = 5;
+}