Skip to content

feat (AIP-136) Update guidance of billable stateless methods #1124

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
xdtdaniel wants to merge 9 commits into
base: master
Choose a base branch
from
Open

feat (AIP-136) Update guidance of billable stateless methods #1124

Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
c9105e7
Update 0136.md for guidance of billable stateless methods
xdtdaniel May 31, 2023
4871799
Merge branch 'master' into master
toumorokoshi Jun 2, 2023
7fd7b34
Clarify on the why the cacheable requests should use GET
xdtdaniel Jun 3, 2023
c43b4c5
Update 0136.md
xdtdaniel Jun 7, 2023
85f1829
Update 0136.md to reflect current date
xdtdaniel Jun 7, 2023
4426da2
Merge branch 'master' into master
xdtdaniel Jun 10, 2023
0bcef51
Merge branch 'master' into master
toumorokoshi Jul 5, 2023
b2dcccc
Update 0136.md
xdtdaniel Jul 5, 2023
dd59db2
Merge branch 'master' into master
toumorokoshi Aug 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions aip/general/0136.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
id: 136
state: approved
created: 2019-01-25
updated: 2023-03-02
updated: 2023-05-31
Comment thread
xdtdaniel marked this conversation as resolved.
Outdated
placement:
category: operations
order: 100
Expand Down Expand Up @@ -127,7 +127,6 @@ rpc TranslateText(TranslateTextRequest) returns (TranslateTextResponse) {
- The URI **should** place both the verb and noun after the `:` separator
(avoid a "faux collection key" in the URI in this case, as there is no
collection). For example, `:translateText` is preferable to `text:translate`.
- Stateless methods **must** use `POST` if they involve billing.

### Declarative-friendly resources

Expand Down Expand Up @@ -174,8 +173,17 @@ RPC name itself causes confusion, and can even cause issues for client libraries
which generate both synchronous and asynchronous methods to call the RPC in some
languages.

### Choice of HTTP methods for stateless methods

Stateless method **should** use `GET` HTTP method for retrieval use cases due to
its cache-friendly nature. This can reduce the costs for both the server and the
Copy link
Copy Markdown
Contributor

@toumorokoshi toumorokoshi Jun 2, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it might be worth elaborating: e.g. it's common for web browsers to cache GET requests, and it's understood by clients to be a cacheable response.

Copy link
Copy Markdown
Author

@xdtdaniel xdtdaniel Jun 2, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the review! Can you elaborate a bit more on "and it's understood by clients to be a cacheable response" part? What does this mean? Specifically what is "it" referring to? Thanks!

Copy link
Copy Markdown
Contributor

@toumorokoshi toumorokoshi Jun 2, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, by "it" I was referring to the fact that GET methods are cacheable.

and it's understood by clients to be a cacheable response

What I mean is HTTP clients often cache GET responses as GET implies that it's doing data retrieval: https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.1. Specficially:

The response to a GET request is cacheable; a cache MAY use it to
satisfy subsequent GET and HEAD requests unless otherwise indicated
by the Cache-Control header field (Section 5.2 of [RFC7234]).

So custom methods which are cacheable and send no payload should use GET.

Copy link
Copy Markdown
Author

@xdtdaniel xdtdaniel Jun 3, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I edited it again with a new commit. PTAL!

client.

Comment thread
xdtdaniel marked this conversation as resolved.
## Changelog

- **2023-05-31:** Remove the guidance that stateless methods involving
billing should use POST. Clarify the choice of HTTP methods for stateless
methods.
- **2023-05-16:** Added prohibition of the term "async" within RPC names.
- **2023-05-09:** Adding guidance for POST and GET, require parent instead of
the resource singular.
Expand Down