Merge pull request #737 from zalando/tfrauenstein-patch-1

Improve guidance for return code usage for (robust) create.

Author: tfrauenstein

chapters/http-requests.adoc

@@ -90,16 +90,20 @@ implicitly creating the resource before updating
 * on successful {PUT} requests, the server will *replace the entire resource*
 addressed by the URL with the representation passed in the payload (subsequent
 reads will deliver the same payload, plus possibly server-generated fields like `modified_at`)
-* successful {PUT} requests will usually generate {200} or {204} (if the
-resource was updated – with or without actual content returned), and {201} (if
-the resource was created)
-
-*Important:* It is good practice to prefer {POST} over {PUT} for creation of
-(at least top-level) resources. This leaves the resource identifier management under
-control of the service and not the client, and focuses {PUT} on its usage for updates.
-However, in situations where all resource attributes including the identifier
+* successful {PUT} requests return {200} or {204} (if the resource was updated - 
+with or without returning the resource), {201} (if the resource was created) 
+or {202} (if accepted and processed asynchronously).
+
+The updated/created resource may be returned as response payload. We recommend, 
+to not use it per default, but if the resource is enriched with server-generated 
+fields like `version_number`. You may also support client side steering (see <<181>>).
+
+*Important:* It is good practice to keep the resource identifier management under
+control of the service provider and not the client, and, hence, to prefer {POST} for 
+creation of (at least top-level) resources, and focus {PUT} on its usage for updates.
+However, in situations where the identifier and all resource attributes
 are under control of the client as input for the resource creation you should use
-{PUT} and pass the resource identifier via the URL path.
+{PUT} and pass the resource identifier as URL path parameter.
 Putting the same resource twice is required to be <<idempotent>> and to result
 in the same single resource instance (see <<149>>) without data duplication in case of repetition.
 
@@ -122,10 +126,9 @@ by the URL"_.
 
 * on a successful {POST} request, the server will create one or multiple new
 resources and provide their URI/URLs in the response
-* successful {POST} requests will usually generate {200} (if resources have
-been updated), {201} (if resources have been created), {202} (if the request
-was accepted but has not been finished yet), and exceptionally {204} with
-{Location} header (if the actual resource is not returned).
+* successful {POST} requests return {200} or {204} (if the resource was updated - 
+with or without returning the resource), {201} (if the resource was created) 
+or {202} (if accepted and processed asynchronously).
 
 *Note:* By using {POST} to create resources the resource ID must not be passed as
 request input date by the client, but created and maintained by the service and
@@ -159,8 +162,8 @@ collection is challenging
 instances
 * on successful {PATCH} requests, the server will update parts of the resource
 addressed by the URL as defined by the change request in the payload
-* successful {PATCH} requests will usually generate {200} or {204} (if
-resources have been updated with or without updated content returned)
+* successful {PATCH} requests return {200} or {204} (if the resource was updated - 
+with or without returning the resource).
 
 *Note:* since implementing {PATCH} correctly is a bit tricky, we strongly suggest
 to choose one and only one of the following patterns per endpoint (unless
@@ -206,8 +209,8 @@ described as _"please delete the resource identified by the URL"_.
  collection resources, as this would imply deleting the entire collection.
 * {DELETE} request can be applied to multiple resources at once using query
  parameters on the collection resource (see <<delete-with-query-params>>).
-* successful {DELETE} requests will usually generate {200} (if the deleted
- resource is returned) or {204} (if no content is returned).
+* successful {DELETE} requests return {200} or {204} (if the resource was deleted - 
+ with or without returning the resource).
 * failed {DELETE} requests will usually generate {404} (if the resource cannot
  be found) or {410} (if the resource was already deleted before).
 
@@ -374,6 +377,11 @@ If you mainly aim to support safe retries, we suggest to apply <<182,
 conditional key>> and <<231,secondary key>> pattern before the <<230,
 Idempotency Key>> pattern.
 
+Note, like for {PUT}, successful {POST} or {PATCH} returns {200} or {204} (if the resource 
+was updated - with or without returning the resource), or {201} (if resource was created). 
+Hence, clients can differentiate successful robust repetition from resource created
+server activity of idempotent {POST}.
+
 
 [#231]
 == {Should} use secondary key for idempotent `POST` design

chapters/http-status-codes-and-errors.adoc

@@ -84,22 +84,23 @@ a clear description of the HTTP status code in the response.
 |=======================================================================
 |Code |Meaning |Methods
 |[[status-code-200]]{200}|
-OK - this is the standard success response
+OK - this is the most general success response and used, 
+if the more specific codes below are not applicable. 
 |{ALL}
 
 |[[status-code-201]]{201}|
-Created - Returned on successful entity creation. You are
-free to return either an empty response or the created resource in conjunction
-with the Location header. (More details found in the <<standard-headers>>.)
-_Always_ set the Location header.
+Created - Returned on successful resource creation. 
+{201} is returned with or without response payload (unlike {200} / {204}).
+We recommend to additionally return the created resource URL via the `Location` 
+response header (see <<standard-headers>>).
 |{POST}, {PUT}
 
 |[[status-code-202]]{202}|
 Accepted - The request was successful and will be processed asynchronously.
 |{POST}, {PUT}, {PATCH}, {DELETE}
 
 |[[status-code-204]]{204}|
-No content - There is no response body.
+No content - Returned instead of {200}, if no response payload is returned. 
 |{PUT}, {PATCH}, {DELETE}
 
 |[[status-code-207]]{207}|
@@ -175,8 +176,10 @@ Request timeout - the server times out waiting for the resource.
 
 |[[status-code-409]]{409}|
 Conflict - request cannot be completed due to conflict with the current state of the target resource.
-For instance, in situations where two clients try to create the same resource or if there are 
-concurrent, conflicting updates.
+For example, you may get a {409} response when updating a resource that is older than the existing 
+one on the server, resulting in a version control conflict.
+Hint, you should not return {409}, but {200} or {204} in case of successful robust creation of resources 
+(via {PUT} or {POST}), if the resource already exists.
 |{POST}, {PUT}, {PATCH}, {DELETE}
 
 |[[status-code-410]]{410}|