From c9105e7da263a29c07be2d5815a00937de811194 Mon Sep 17 00:00:00 2001 From: Dantong Xue Date: Wed, 31 May 2023 11:42:32 -0700 Subject: [PATCH 1/5] Update 0136.md for guidance of billable stateless methods Proposes changes for AIP-136 regarding the use of GET and POST for stateless methods. --- aip/general/0136.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/aip/general/0136.md b/aip/general/0136.md index d5978885a8..a4c21892a7 100644 --- a/aip/general/0136.md +++ b/aip/general/0136.md @@ -2,7 +2,7 @@ id: 136 state: approved created: 2019-01-25 -updated: 2023-03-02 +updated: 2023-05-31 placement: category: operations order: 100 @@ -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 @@ -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 +client. + ## 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. From 7fd7b34196b55a289d41ee360581535cb57f8a13 Mon Sep 17 00:00:00 2001 From: Dantong Xue Date: Fri, 2 Jun 2023 17:21:03 -0700 Subject: [PATCH 2/5] Clarify on the why the cacheable requests should use GET --- aip/general/0136.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/aip/general/0136.md b/aip/general/0136.md index a4c21892a7..33d2bb45f1 100644 --- a/aip/general/0136.md +++ b/aip/general/0136.md @@ -175,9 +175,10 @@ 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 -client. +HTTP clients such as browsers often cache `GET` responses as `GET` implies that +it is doing data retrieval. Stateless methods that are cacheable and send no +payload **should** use `GET` HTTP method due to its cache-friendly nature. +This can reduce the costs for both the server and the client. ## Changelog From c43b4c5932b4f311305cfb26588153e85881c961 Mon Sep 17 00:00:00 2001 From: Dantong Xue Date: Tue, 6 Jun 2023 20:41:39 -0700 Subject: [PATCH 3/5] Update 0136.md --- aip/general/0136.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/aip/general/0136.md b/aip/general/0136.md index 33d2bb45f1..a21bf3e1e9 100644 --- a/aip/general/0136.md +++ b/aip/general/0136.md @@ -180,6 +180,9 @@ it is doing data retrieval. Stateless methods that are cacheable and send no payload **should** use `GET` HTTP method due to its cache-friendly nature. This can reduce the costs for both the server and the client. +If the stateless method is not cacheable by design, it **should** use `POST` +HTTP method to prevent the response being cached. + ## Changelog - **2023-05-31:** Remove the guidance that stateless methods involving From 85f18293cb10f4c4f2e97e5a9272b5a60f42a452 Mon Sep 17 00:00:00 2001 From: Dantong Xue Date: Tue, 6 Jun 2023 20:43:20 -0700 Subject: [PATCH 4/5] Update 0136.md to reflect current date --- aip/general/0136.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aip/general/0136.md b/aip/general/0136.md index a21bf3e1e9..33c2a427cf 100644 --- a/aip/general/0136.md +++ b/aip/general/0136.md @@ -2,7 +2,7 @@ id: 136 state: approved created: 2019-01-25 -updated: 2023-05-31 +updated: 2023-06-06 placement: category: operations order: 100 @@ -185,7 +185,7 @@ HTTP method to prevent the response being cached. ## Changelog -- **2023-05-31:** Remove the guidance that stateless methods involving +- **2023-06-06:** 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. From b2dcccc03160b489ef5c5fc7a0aba1cd17cec1e9 Mon Sep 17 00:00:00 2001 From: Dantong Xue Date: Wed, 5 Jul 2023 13:35:38 -0700 Subject: [PATCH 5/5] Update 0136.md --- aip/general/0136.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/aip/general/0136.md b/aip/general/0136.md index 33c2a427cf..7f391b9827 100644 --- a/aip/general/0136.md +++ b/aip/general/0136.md @@ -180,9 +180,6 @@ it is doing data retrieval. Stateless methods that are cacheable and send no payload **should** use `GET` HTTP method due to its cache-friendly nature. This can reduce the costs for both the server and the client. -If the stateless method is not cacheable by design, it **should** use `POST` -HTTP method to prevent the response being cached. - ## Changelog - **2023-06-06:** Remove the guidance that stateless methods involving