feat: AIP-131 – GET for individual resources (#2)

Author: Luke Sneeringer

aip/general/0131/aip.md.j2

@@ -0,0 +1,129 @@
+# GET for individual resources
+
+In REST APIs, it is customary to make a `GET` request to a resource's URI (for
+example, `/v1/publishers/{publisher}/books/{book}`) in order to retrieve that
+resource.
+
+Our APIs honor this pattern by allowing `GET` requests to be sent to the
+resource URI, which returns the resource itself.
+
+## Guidance
+
+APIs **should** generally provide a `GET` method for resources unless it is not
+valuable for users to do so. When the `GET` method is used on a URI ending in a
+resource ID or resource ID alias, the result should be a single resource. For
+more information about using the `GET` method on a URI ending with a resource
+collection identifier, see AIP-132.
+
+### Requests
+
+Single-resource `GET` operations **must** be made by sending a `GET` request to
+the resource's URI:
+
+```http
+GET /v1/publishers/{publisher}/books/{book} HTTP/2
+Host: library.googleapis.com
+Accept: application/json
+```
+
+- The HTTP method **must** be `GET`.
+  - The request **must** be safe and **must not** have side effects.
+- There **must not** be a request body.
+  - If a `GET` request contains a body, the body **must** be ignored, and
+    **must not** cause an error.
+- The request **must not** require any fields in the query string. The request
+  **should not** include optional fields in the query string unless described
+  in another AIP.
+
+### Responses
+
+Single-resource `GET` operations **must** return the resource itself, without
+any additional wrapping:
+
+```json
+{
+  "name": "publishers/lacroix/books/les-mis",
+  "isbn": "978-037-540317-0",
+  "title": "Les Misérables",
+  "authors": ["Victor Hugo"],
+  "rating": 9.6
+}
+```
+
+### Errors
+
+If the user does not have sufficient permission to know that the resource
+exists, the service **should** reply with an HTTP 404 error, regardless of
+whether or not the resource exists. Permission **must** be checked prior to
+checking if the resource exists.
+
+If the user has sufficient permission to know that the resource exists, but is
+unable to access it, the service **should** reply with an HTTP 403 error.
+
+If the user does have proper permission, but the requested resource does not
+exist, the service **must** reply with an HTTP 404 error.
+
+## Interface Definitions
+
+{% tab proto -%}
+
+Get operations are specified using the following pattern:
+
+{% sample 'get.proto', 'rpc GetBook' %}
+
+- The RPC's name **must** begin with the word `Get`. The remainder of the RPC
+  name **should** be the singular form of the resource's message name.
+- The request message **must** match the RPC name, with a `-Request` suffix.
+- The response message **must** be the resource itself. (There is no
+  `GetBookResponse`.)
+  - The response **should** usually include the fully-populated resource unless
+    there is a reason to return a partial response (see AIP-157).
+- The HTTP verb **must** be `GET`.
+- The URI **should** contain a single variable field corresponding to the
+  resource name.
+  - This field **should** be called `name`.
+  - The URI **should** have a variable corresponding to this field.
+  - The `name` field **should** be the only variable in the URI path. All
+    remaining parameters **should** map to URI query parameters.
+- There **must not** be a `body` key in the `google.api.http` annotation.
+- There **should** be exactly one `google.api.method_signature` annotation,
+  with a value of `"name"`.
+
+Get operations also implement a common request message pattern:
+
+{% sample 'get.proto', 'message GetBookRequest' %}
+
+- A resource name field **must** be included. It **should** be called `name`.
+  - The field **should** be annotated as required.
+  - The field **should** identify the [resource type][aip-123] that it
+    references.
+- The comment for the `name` field **should** document the resource pattern.
+- The request message **must not** contain any other required fields, and
+  **should not** contain other optional fields except those described in
+  another AIP.
+
+**Note:** The `name` field in the request object corresponds to the `name`
+variable in the `google.api.http` annotation on the RPC. This causes the `name`
+field in the request to be populated based on the value in the URL when the
+REST/JSON interface is used.
+
+{% tab oas %}
+
+Single-resource `GET` operations **must** be specified with consistent OpenAPI
+metadata:
+
+{% sample 'get.oas.yaml', 'paths' %}
+
+- The `operationId` **must** begin with the word `get`. The remainder of the
+  `operationId` **should** be the singular form of the resource type's name.
+- The response content **must** be the resource itself. For example:
+  `#/components/schemas/Book`
+  - The response **should** usually include the fully-populated resource unless
+    there is a reason to return a partial response (see AIP-157).
+- The URI **should** contain a variable for each individual ID in the resource
+  hierarchy.
+  - The path parameter for all resource IDs **must** be in the form
+    `{resourceName}Id` (such as `bookId`), and path parameters representing the
+    ID of parent resources **must** end with `Id`.
+
+{% endtabs %}

aip/general/0131/aip.yaml

@@ -0,0 +1,7 @@
+---
+id: 131
+state: approved
+created: 2019-01-22
+placement:
+  category: operations
+  order: 10

aip/general/0131/get.oas.yaml

@@ -0,0 +1,42 @@
+---
+openapi: 3.0.3
+info:
+  title: Library
+  version: 1.0.0
+paths:
+  /publishers/{publisherId}/books/{bookId}:
+    get:
+      operationId: getBook
+      description: Get a single book.
+      responses:
+        200:
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Book'
+components:
+  schema:
+    Book:
+      description: A representation of a single book.
+      properties:
+        name:
+          type: string
+          description: |
+            The name of the book.
+            Format: publishers/{publisher}/books/{book}
+        isbn:
+          type: string
+          description: |
+            The ISBN (International Standard Book Number) for this book.
+        title:
+          type: string
+          description: The title of the book.
+        authors:
+          type: array
+          items:
+            type: string
+          description: The author or authors of the book.
+        rating:
+          type: float
+          description: The rating assigned to the book.

aip/general/0131/get.proto

@@ -0,0 +1,61 @@
+// 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/http.proto";
+import "google/api/resource.proto";
+
+service Library {
+  // Get a single book.
+  rpc GetBook(GetBookRequest) returns (Book) {
+    option (google.api.http) = {
+      get: "/v1/{name=publishers/*/books/*}"
+    };
+    option (google.api.method_signature) = "name";
+  }
+}
+
+// Request message to get a single book.
+message GetBookRequest {
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "library.googleapis.com/Book"
+    }];
+}
+
+// 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;
+}