feat: improve response code guidance (#787, #762, #737)

Signed-off-by: tkrop <[email protected]>

chapters/http-requests.adoc

@@ -119,15 +119,18 @@ details and options.
 collection resource endpoint, but other semantics on single resources endpoint
 are equally possible. The semantic for collection endpoints is best described
 as _"please add the enclosed representation to the collection resource
-identified by the URL"_. The semantic for single resource endpoints is best described
-as _"please execute the given well specified request on the resource identified
-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 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).
+identified by the URL"_. The semantic for single resource endpoints is best
+described as _"please execute the given well specified request on the resource
+identified by the URL"_.
+
+* On a successful {POST} request, the server will create one or multiple new
+  resources, usually returning them (or their URI/URLs) in the response. For a
+  single resource, the {POST} is expected to uses the {Location} header to
+  point to the URL of the newly created resource.
+* Successful {POST} requests return {200} or {204} if the resource was updated
+  -- with or without returning the resource --, {201} if the resource was newly
+  created, and {202} if the request was accepted and is 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
@@ -156,13 +159,13 @@ defined in {RFC-5789}[RFC-5789] and must be described in the API specification
 by using specific media types.
 
 * {PATCH} requests are usually applied to single resources as patching entire
-collection is challenging
+  collection is challenging.
 * {PATCH} requests are usually not robust against non-existence of resource
-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 return {200} or {204} (if the resource was updated - 
-with or without returning the resource).
+  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 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
@@ -262,7 +265,7 @@ be similar to usual {DELETE} requests.
 resources and resource collections.
 
 * {HEAD} has exactly the same semantics as {GET}, but returns headers only, no
-body.
+  body.
 
 *Hint:* {HEAD} is particular useful to efficiently lookup whether large
 resources or collection resources have been updated in conjunction with the
@@ -276,7 +279,7 @@ resources or collection resources have been updated in conjunction with the
 methods) of a given endpoint.
 
 * {OPTIONS} responses usually either return a comma separated list of methods
-in the `Allow` header or as a structured list of link templates
+  in the `Allow` header or as a structured list of link templates.
 
 *Note:* {OPTIONS} is rarely implemented, though it could be used to
 self-describe the full functionality of a resource.
@@ -375,12 +378,12 @@ following table showing the major properties of each pattern:
 
 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.
+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}.
+*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]