Add suggested changes from API guild discussion (POST usage) #791
Conversation
|
I'm a bit hesitant to approve this, because the pull request majorly splits up the dense description from before into 4 subsections without providing additional clarification that wasn't clear from the before context. In my opinion the deeper nesting is not preferable here. The wording improvements are fine and could be added to the before structure too. |
Co-authored-by: Tronje Krop <[email protected]>
You're right, looking at it again it seems a bit too wordy. However, the previous dense description seemed a bit too overloaded, so there was a lot to interpret. Maybe there's a good structure somewhere in the middle? I'll have to take another look :) Either way, I applied the suggestions, thanks! |
|
👍 |
|
👍 |
ePaul
changed the title
chapters/http-requests.adoc
Outdated
| * For multiple resources you {SHOULD} return {201} in the response, as long as | ||
| they are created atomically, meaning that either all the resources are created | ||
| or none of them are. | ||
| ** You <<152>> if the request can partially fail, that is some of the resources | ||
| can fail to be created. | ||
| * If the response does not contain the created resource or a resource monitor, | ||
| the status code {SHOULD} be {201} and the URL to {GET} the resource {MUST} be | ||
| provided in the {Location} response header. | ||
| * If the {POST} is <<idempotent>>, the status code {SHOULD} be {201} if the | ||
| resource was created and {200} or {204} if the resource was updated. |
There was a problem hiding this comment.
I wonder whether these last two bullet points are more applicable for the single-resource case? They certainly don't fit for the "return 207" case. Maybe move them as sub-bullet-points to the single-resource case?
There was a problem hiding this comment.
Good point! I'll do that
|
@ePaul I added your suggestion, please check again! |
|
👍 |
1 similar comment
|
👍 |
I took some liberties on the formatting/wording, but mostly it's as discussed in the internal doc.