You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat(132-135): standardize on a format for standard methods (#246)
The standard method AEPs have a bit of inconsistency
in the format and the examples they provide.
This PR proposes a format to normalize them all to, including
the following headings:
- Overview: a brief explanation of the method
- Guidance: a brief explanation of the purpose
- Operation: an example operation, with must/should guidance
- Request: an example request, with must/should guidance
- Response: an example request, with must/should guidance
- Errors: explanation on errors, if applicable
- (additional guidance sections specific to the AEP)
- Interface Definitions: a full example of the operation, request, and response.
This will result in some incomplete sections: those will be filled out via
follow-up PRs to keep this from becoming too massive.
Copy file name to clipboardexpand all lines: aep/general/0131/aep.md.j2
+76-66
Original file line number
Diff line number
Diff line change
@@ -14,17 +14,72 @@ resource.
14
14
is to return data from a single resource.
15
15
- Some resources take longer to be retrieved than is reasonable for a regular API request. In this situation, the API should use a [long-running operation](/long-running-operations).
16
16
17
-
### Requests
17
+
### Operation
18
+
19
+
{%tabproto%}
20
+
21
+
{%sample'../example.proto', 'rpc GetBook'%}
22
+
23
+
- The RPC's name **must** begin with the word `Get`. The remainder of the RPC
24
+
name **should** be the singular form of the resource's message name.
25
+
- The request message **must** match the RPC name, with a `Request` suffix.
26
+
- The response message **must** be the resource itself. (There is no
27
+
`GetBookResponse`.)
28
+
- The HTTP verb **must** be `GET`.
29
+
- The URI **should** contain a single variable field corresponding to the
30
+
resource path.
31
+
- This field **should** be called `path`.
32
+
- The URI **should** have a variable corresponding to this field.
33
+
- The `path` field **should** be the only variable in the URI path. All
34
+
remaining parameters **should** map to URI query parameters.
35
+
- There **must not** be a `body` key in the `google.api.http` annotation.
36
+
- There **should** be exactly one `google.api.method_signature` annotation,
37
+
with a value of `"path"`.
38
+
39
+
{%taboas%}
18
40
19
41
`Get` operations **must** be made by sending a `GET` request to the resource's
20
42
URI:
21
43
22
44
```http
23
45
GET /v1/publishers/{publisher}/books/{book} HTTP/2
24
-
Host: library.example.com
46
+
Host: bookstore.example.com
25
47
Accept: application/json
26
48
```
27
49
50
+
- The URI **should** contain a variable for each resource in the resource
51
+
hierarchy.
52
+
- The path parameter for all resource IDs **must** be in the form
0 commit comments