feat: improve response (code) guidance (#787, #762, #737) #789
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: tkrop <[email protected]>
tkrop
commented
Nov 22, 2023
Comment on lines
+133
to
+138
| * For a single resource (tree) {POST} is expected to utilize the {Location} | ||
| header pointing to the URL of the newly created resource (tree) -- with or | ||
| without returning the resource (tree). | ||
| * For multiple resources {POST} may either return a collection of newly | ||
| created resources as served by the {GET} collection endpoint, or a bulk | ||
| response using the status code {207} (see also <<152>>). |
There was a problem hiding this comment.
Tries to clarify on how to return created resources with respect to id and location.
There was a problem hiding this comment.
I'm not convinced that we always should require the Location response header.
Propose the following change:
- {POST} must be used to create one or multiple new resources:
- Single resource creation: successful POST should return the new resource
object as response payload including the resource id. We expect that the resource id
can be used as a path parameter of the GET endpoint to read the resource. The URL to read
the resource must be provided via the Location response header, if the resource is
not returned. It is a good practice to always provide the Location header. - Multiple resource creation: successful {POST} may either return a collection of newly
created resources as served by the {GET} collection endpoint, or a bulk
response using the status code {207} (see also <<152>>).
- Single resource creation: successful POST should return the new resource
There was a problem hiding this comment.
See #791 for the proposed changes from the discussion.
tkrop
commented
Nov 22, 2023
Comment on lines
+224
to
+226
| * Successful {DELETE} requests return {200} or {204} (if the resource was | ||
| deleted -- with or without returning the resource), or {202} (if the request | ||
| was accepted for asynchronous processing). |
tkrop
commented
Nov 22, 2023
Comment on lines
+176
to
+178
| * Successful {PATCH} requests return {200} or {204} (if the resource was | ||
| updated -- with or without returning the resource), and {202} (if the request | ||
| was accepted for asynchronous processing). |
|
👍 |
1 similar comment
|
👍 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This pull request was starting from the still open issue #685 (originally addressed by #737) and the latest work done in #787 trying to grab the open ends and missed links to add more guidance on the correct usage of
Locationheader inPOSTresponses. While doing so I was also doing the review on #762, I was lacking behind.Changes to
chapters/http-requests.adoc:202as expected response codes onPUTandPATCHoperations, since they may also support asynchronous processing.POSTresponses utilizing theLocationheader.Changes to
chapters/http-status-codes-and-errors.adoc:200response code marks the return of an already existing resource on resource creation.3xxresponse code. Before it incorrectly referenced rule 250 and was added to the chapter of3xxresponse codes.use-advise to response codes406,412,415,428,500, and503to highlight response codes that have use case defined within the guideline.423,500,501, and503giving details on use cases.424,431,502,504,505,507, and511to complete the list of response codes defined by the three incorporated and referenced RFCs 9110, 6585, and 4918.Definitely fixes #685.