zalando / restful-api-guidelines

A model set of guidelines for RESTful APIs and Events, created by Zalando
https://opensource.zalando.com/restful-api-guidelines/
Creative Commons Attribution 4.0 International
2.63k stars 387 forks source link

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

Closed tkrop closed 10 months ago

tkrop commented 11 months ago

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 Location header in POST responses. While doing so I was also doing the review on #762, I was lacking behind.

Changes to chapters/http-requests.adoc:

  1. Apply standard formatting rules for asciidoc/markdown and fixes spelling and grammar issues (all major changes are marked with comments and exposed in this list).
  2. Adds 202 as expected response codes on PUT and PATCH operations, since they may also support asynchronous processing.
  3. Adds better advise on how to design POST responses utilizing the Location header.

Changes to chapters/http-status-codes-and-errors.adoc:

  1. Apply standard formatting rules for asciidoc/markdown and fixes spelling and grammar issues (all major changes are exposed in this list and can be easily spotted in the change set).
  2. Improved exception when to document response codes explicitly.
  3. Added advise when 200 response code marks the return of an already existing resource on resource creation.
  4. FIx reference to rule 251 and added it to each effected 3xx response code. Before it incorrectly referenced rule 250 and was added to the chapter of 3xxresponse codes.
  5. Added additional use-advise to response codes 406, 412, 415, 428, 500, and 503 to highlight response codes that have use case defined within the guideline.
  6. Improved advise for response code 423, 500, 501, and 503 giving details on use cases.
  7. Added advise for response codes 424, 431, 502, 504, 505, 507, and 511 to complete the list of response codes defined by the three incorporated and referenced RFCs 9110, 6585, and 4918.

Definitely fixes #685.

tfrauenstein commented 10 months ago

👍

tkrop commented 10 months ago

👍