Skip to content

Commit 53da5a2

Browse files
authored
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.
1 parent cc9c261 commit 53da5a2

15 files changed

+1017
-700
lines changed

aep/general/0131/aep.md.j2

+76-66
Original file line numberDiff line numberDiff line change
@@ -14,17 +14,72 @@ resource.
1414
is to return data from a single resource.
1515
- 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).
1616

17-
### Requests
17+
### Operation
18+
19+
{% tab proto %}
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+
{% tab oas %}
1840

1941
`Get` operations **must** be made by sending a `GET` request to the resource's
2042
URI:
2143

2244
```http
2345
GET /v1/publishers/{publisher}/books/{book} HTTP/2
24-
Host: library.example.com
46+
Host: bookstore.example.com
2547
Accept: application/json
2648
```
2749

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
53+
`{resource-singular}` (such as `book`).
54+
55+
{% endtabs %}
56+
57+
### Requests
58+
59+
{% tab proto %}
60+
61+
{% sample '../example.proto', 'message GetBookRequest' %}
62+
63+
- A resource path field **must** be included. It **should** be called `path`.
64+
- The field **should** be annotated as `REQUIRED`.
65+
- The field **should** identify the [resource type][aep-4] that it
66+
references.
67+
- The comment for the `path` field **should** document the resource pattern.
68+
- The request message **must not** contain any other required fields, and
69+
**should not** contain other optional fields except those described in
70+
another AEP.
71+
72+
**Note:** The `path` field in the request object corresponds to the `path`
73+
variable in the `google.api.http` annotation on the RPC. This causes the `path`
74+
field in the request to be populated based on the value in the URL when the
75+
REST/JSON interface is used.
76+
77+
[aep-4]: ./0004.md
78+
79+
{% tab oas %}
80+
81+
{% sample '../example.oas.yaml', '$.paths./publishers/{publisher}/books/{book}.get.parameters' %}
82+
2883
- The HTTP method **must** be `GET`.
2984
- The request **must** be safe and **must not** have side effects.
3085
- There **must not** be a request body.
@@ -34,24 +89,26 @@ Accept: application/json
3489
**should not** include optional fields in the query string unless described
3590
in another AEP.
3691

37-
### Responses
92+
{% endtabs %}
3893

39-
Single-resource `GET` operations **must** return the resource itself, without
40-
any additional wrapping:
41-
42-
```json
43-
{
44-
"name": "publishers/lacroix/books/les-mis",
45-
"isbn": "978-037-540317-0",
46-
"title": "Les Misérables",
47-
"authors": ["Victor Hugo"],
48-
"rating": 9.6
49-
}
50-
```
94+
### Responses
5195

5296
The response **should** usually include the fully-populated resource unless
5397
there is a reason to return a partial response (see AEP-157).
5498

99+
{% tab proto %}
100+
101+
{% sample '../example.proto', 'message Book' %}
102+
103+
{% tab oas %}
104+
105+
{% sample '../example.oas.yaml', '$.paths./publishers/{publisher}/books/{book}.get.responses.200.content' %}
106+
107+
- The response content **must** be the resource itself. For example:
108+
`#/components/schemas/Book`. The response **must** reference a schema with a `x-aep-resource` extension.
109+
110+
{% endtabs %}
111+
55112
### Errors
56113

57114
If the user does not have sufficient permission to know that the resource
@@ -69,61 +126,14 @@ exist, the service **must** reply with an HTTP 404 error.
69126

70127
{% tab proto -%}
71128

72-
Get operations are specified using the following pattern:
129+
{% sample '../example.proto', 'rpc GetBook' %}
73130

74-
{% sample 'get.proto', 'rpc GetBook' %}
131+
{% sample '../example.proto', 'message GetBookRequest' %}
75132

76-
- The RPC's name **must** begin with the word `Get`. The remainder of the RPC
77-
name **should** be the singular form of the resource's message name.
78-
- The request message **must** match the RPC name, with a `Request` suffix.
79-
- The response message **must** be the resource itself. (There is no
80-
`GetBookResponse`.)
81-
- The HTTP verb **must** be `GET`.
82-
- The URI **should** contain a single variable field corresponding to the
83-
resource path.
84-
- This field **should** be called `path`.
85-
- The URI **should** have a variable corresponding to this field.
86-
- The `path` field **should** be the only variable in the URI path. All
87-
remaining parameters **should** map to URI query parameters.
88-
- There **must not** be a `body` key in the `google.api.http` annotation.
89-
- There **should** be exactly one `google.api.method_signature` annotation,
90-
with a value of `"path"`.
91-
92-
Get operations also implement a common request message pattern:
93-
94-
{% sample 'get.proto', 'message GetBookRequest' %}
95-
96-
- A resource path field **must** be included. It **should** be called `path`.
97-
- The field **should** be annotated as `REQUIRED`.
98-
- The field **should** identify the [resource type][aep-4] that it
99-
references.
100-
- The comment for the `path` field **should** document the resource pattern.
101-
- The request message **must not** contain any other required fields, and
102-
**should not** contain other optional fields except those described in
103-
another AEP.
104-
105-
**Note:** The `path` field in the request object corresponds to the `path`
106-
variable in the `google.api.http` annotation on the RPC. This causes the `path`
107-
field in the request to be populated based on the value in the URL when the
108-
REST/JSON interface is used.
109-
110-
[aep-4]: ./0004.md
133+
{% sample '../example.proto', 'message Book' %}
111134

112135
{% tab oas %}
113136

114-
Single-resource `GET` operations **must** be specified with consistent OpenAPI
115-
metadata:
116-
117-
{% sample 'get.oas.yaml', 'paths' %}
118-
119-
- The `operationId` **must** begin with the word `get`. The remainder of the
120-
`operationId` **should** be the singular form of the resource type's name.
121-
- The response content **must** be the resource itself. For example:
122-
`#/components/schemas/Book`. The response **must** reference a schema with a `x-aep-resource` extension.
123-
- The URI **should** contain a variable for each individual ID in the resource
124-
hierarchy.
125-
- The path parameter for all resource IDs **must** be in the form
126-
`{resourceName}Id` (such as `bookId`), and path parameters representing the
127-
ID of parent resources **must** end with `Id`.
137+
{% sample '../example.oas.yaml', '$.paths./publishers/{publisher}/books/{book}.get' %}
128138

129139
{% endtabs %}

aep/general/0131/get.oas.yaml

-52
This file was deleted.

aep/general/0131/get.proto

-64
This file was deleted.

0 commit comments

Comments
 (0)