Skip to content

Commit

Permalink
Adaptations after Rest Design workgroup of 9 Sept for:
Browse files Browse the repository at this point in the history 
update tables with http status codes and verbs #40
removing selection of items from a collection #65
  • Loading branch information
@smals-chlo
smals-chlo committed Sep 11, 2020
1 parent 3045b9d commit dd8ca3e
Show file tree
Hide file tree
Showing 4 changed files with 108 additions and 208 deletions.
13 changes: 7 additions & 6 deletions src/main/asciidoc/changelog.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
== Changelog
* 2020-xx-xx
** added: <<remove-collection-items, removing a selection of items from a collection>> (<<Collection, Collection>>)
** cleanup of status codes in various locations like <<Collection>>, <<Document>>, <<HTTP Methods>> and <<status-codes>>
** added: status code <<http-429, 429 Too Many Requests>> (<<status-codes>>)
** added tables when to use each HTTP method (<<HTTP Methods, HTTP Methods>>)
** move common OpenAPI schemas to separate GitHub repositories (<<belgif-openapi-types>>)
* 2020-09-18
** add: <<remove-collection-items, Remove a selection of items from a collection>> (<<Collection, Collection>>)
** improve of status codes in various locations like <<Collection>>, <<Document>>, <<HTTP Methods>> and <<status-codes>>
** add: status codes <<http-429, 429 Too Many Requests>> and <<http-502, 502 Bad Gateway>> (<<status-codes>>)
** add overview table about how to use each HTTP method (<<HTTP Methods, HTTP Methods>>)
** add overview table about acceptable Status Codes for each method (<<HTTP Methods, HTTP Methods>>)
* 2020-08-03
** allow OpenAPI 3.0 (<<api-specs>>)
** remove unmaintained swagger-validator-maven-plugin and styleguide-validationrules from tools list (<<openapi-tools>>)
Expand Down
290 changes: 89 additions & 201 deletions src/main/asciidoc/methods.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,66 +3,15 @@
=== GET
**GET must be used to retrieve a representation of a resource.** It is a strict read-only method, which should never modify the state of the resource.

**​​How to use GET**
[cols="1,2,3,4,5", options="header"]
|===
|Collection
|Document
|Controller
|Request body
|Response body

|Yes
|Yes
|Yes
|Empty
|Resource(s)
|===

**​​Status codes**

[cols="1,3", options="header"]
|===
|​Code|Description​
|​<<http-200,200 OK>>|​The requested resource was found and the search request returns some content.
|<<http-400,400 Bad request>>
|The input data is not valid according the data schema.
|​​<<http-404,404 Not found>> |The requested resource not found.

|===

WARNING: ​<<http-204,204 No content>> should not be used with GET.

=== HEAD
**HEAD should be used to only retrieve the HTTP response headers​.** HEAD returns the same response as GET, except that the API returns an empty body. It is strictly read-only.

**​​How to use HEAD**
[cols="1,2,3,4,5", options="header"]
|===
|Collection
|Document
|Controller
|Request body
|Response body

|Yes
|Yes
|Yes
|Empty
|Empty


|===
=== POST
*POST must be used to create a new resource in a collection or to execute a <<Controller,controller>> resource.*

**​​Status codes**
The POST request’s body contains the suggested state representation of the new resource to be added to the server-owned collection. The response should contain a Location HTTP header containing the newly created URI.

[cols="1,3", options="header"]
|===
|​Code|Description​
|​<<http-200,200 OK>>|​The requested resource was found and the search request returns some content.
|<<http-204,204 No content>> |The search request returns no result.
|​​<<http-404,404 Not found>> |The requested resource was not found.
|===
POST operations may have side effects (i.e. modify state), and are not required to be idempotent.

=== PUT
**PUT must be used to update a stored resource under a consumer supplied URI.** It could be used to insert a new resource in case the client application decides on the resource identifier.
Expand All @@ -73,180 +22,84 @@ If the URI does not point to an existing resource, and that URI is capable of be

PUT operations may have side effects (i.e. modify state), but MUST be idempotent.

**​​How to use PUT**
[cols="1,2,3,4,5", options="header"]
|===
|Collection
|Document
|Controller
|Request body
|Response body

|No
|Yes
|No
|Representation of the updated resource
|Optional

|===
=== PATCH
*PATCH must be used to update partially a representation of a resource.*

**​​Status codes**
The enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version.
The PATCH method affects the resource identified by the Request-URI, and it also MAY have side effects on other resources; i.e., new resources may be created, or existing ones modified, by the application of a PATCH.​
PATCH operations are not required to be idempotent, however they will often be in pratice.

[cols="1,3", options="header"]
|===
|​Code|Description​
|​<<http-200,200 OK>> |The existing resource is updated and the update is returned.​
|<<http-201,201 Created>> |A new resource is created and returned.
See <<Partial update>> on how to specify the set of instructions describing how a resource on the server should be modified.

​​|<<http-204,204 No Content>>
|The existing resource is updated but the update is not returned.​

|<<http-400,400 Bad request>>
|The input data is not valid according the data schema.
**Compatibility**

|<<http-404,404 Not Found>>
|The resource does not exist and thus cannot be updated.
​
​​|<<http-409,409 Conflict>> |A constraint on the resource is violated.
|===
The PATCH http method may not be supported in all components participating in the communication (e.g. HTTP client, intermediary proxy).
If these can't be upgraded to add support, client and server may agree to work around this by implementing PATCH as POST operations with HTTP header 'X-HTTP-Method-Override: PATCH'.

=== POST
*POST must be used to create a new resource in a collection or to execute a <<Controller,controller>> resource.*
=== DELETE
*DELETE must be used to remove a resource from its parent.* Once a DELETE request has been processed for a given resource, the resource can no longer be found by clients. Therefore, any future attempt to retrieve the resource’s state representation, using either GET or HEAD, must result in a 404 (“Not Found”)​ status returned by the API.

The POST request’s body contains the suggested state representation of the new resource to be added to the server-owned collection.

The response should contain a Location HTTP header containing the newly created URI.
=== OPTIONS
OPTIONS should be used to retrieve metadata that describes a resource’s available interactions.

POST operations may have side effects (i.e. modify state), and are not required to be idempotent.

=== Overview table 1: How to use each method

**​​How to use POST**
[cols="1,2,3,4,5", options="header"]
[cols="1,1,1,1,4,2", options="header"]
|===
|Collection
|Document
|Method
|Collection|Document
|Controller
|Request body
|Response body

|GET
|Yes
|Yes
|Yes
|Empty
|Resource(s)

|HEAD
|Yes
|Yes
|Yes
|Empty
|Empty

|POST
|Yes
|No
|Yes
|Representation of the created resource
or controller info
|Optional

|===

**​​Status codes**

[cols="1,3", options="header"]
|===
|​Code|Description​
|​<<http-201,201>> Created|A new resource is created.
|<<http-409,409>> Conflict|The resource already exists.
|<<http-303,303>> See Other |
The resource already exists. The Location header refers to the resource.
|===

WARNING: <<http-200,200 OK>> should not be used with POST.


=== PATCH
*PATCH must be used to update partially a representation of a resource.*

The enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version.
The PATCH method affects the resource identified by the Request-URI, and it also MAY have side effects on other resources; i.e., new resources may be created, or existing ones modified, by the application of a PATCH.​
PATCH operations are not required to be idempotent, however they will often be in pratice.

See <<Partial update>> on how to specify the set of instructions describing how a resource on the server should be modified.

**​​How to use PATCH**
[cols="1,2,3,4,5", options="header"]
|===
|Collection
|Document
|Controller
|Request body
|Response body
|PUT
|No
|Yes
|No
|Representation of the updated resource
|Optional

|PATCH
|No
|Yes
|No
|Fields of the resource to update
|Optional

|===

**​​Status codes**

[cols="1,3", options="header"]
|===
|​Code|Description​
|​<<http-200,200 OK>> |​The existing resource is updated and the update is returned.​
​​|<<http-204,204 No Content>>
|The existing resource is updated but the update is not returned.​
|<<http-400,400 Bad request>>
|The input data is not valid according the data schema.
|​<<http-404,404 Not Found>> |The resource does not exist and thus cannot be updated.
|​<<http-409,409 Conflict>> |A constraint on the resource is violated.​

|===

**Compatibility**

The PATCH http method may not be supported in all components participating in the communication (e.g. HTTP client, intermediary proxy).
If these can't be upgraded to add support, client and server may agree to work around this by implementing PATCH as POST operations with HTTP header 'X-HTTP-Method-Override: PATCH'.

=== DELETE
*DELETE must be used to remove a resource from its parent.* Once a DELETE request has been processed for a given resource, the resource can no longer be found by clients. Therefore, any future attempt to retrieve the resource’s state representation, using either GET or HEAD, must result in a 404 (“Not Found”)​ status returned by the API.

**​​How to use DELETE**
[cols="1,2,3,4,5", options="header"]
|===
|Collection
|Document
|Controller
|Request body
|Response body

|DELETE
|Yes
|Yes
|No
|Empty
|Optional

|===

**​​Status codes**

[cols="1,3", options="header"]
|===
|​Code|Description​
|<<http-200,200 OK>>
|Success code with the deleted resource returned.

|<<http-204,204 No Content>>
|Success code with the deleted resource not returned.

|<<http-400,400 Bad request>>
|Generic error on client side. For example, the syntax of the request is invalid.

|<<http-404,404 Not Found>>
|The resource does not exist and thus cannot be deleted.
|===

=== OPTIONS
OPTIONS should be used to retrieve metadata that describes a resource’s available interactions.

**​​How to use OPTIONS**
[cols="1,2,3,4,5", options="header"]
|===
|Collection
|Document
|Controller
|Request body
|Response body

|OPTIONS
|Yes
|Yes
|No
Expand All @@ -255,13 +108,48 @@ OPTIONS should be used to retrieve metadata that describes a resource’s availa

|===

**​​Status codes**

[cols="1,3", options="header"]
|===
|​Code|Description​
|​<<http-200,200 OK>> | Data is returned successfully and the response body returns some content.
|​<<http-204,204 No content>> | Data is returned successfully with no response body.
|===
=== Overview table 2: Status Code for each method
[cols="3,1,1,2,1,1,1,1", options="header"]
|===
|Code
|GET
|HEAD
|PUT
|POST
|PATCH
|DELETE
|OPTIONS

|<<http-200,200 OK>>
|X
|X
|X
|Only controller
|X
|X
|X

|<<http-201,201 Created>> |- |- |If creation |X |- |- |-
|<<http-202,202 Accepted>> |- |- |- |X |- |- |X
|<<http-204,204 No Content>> |No |X |X |X |X |X |-
|<<http-301,301 Moved Permanently>> |X |X |X |X |X |X |X
|<<http-303,303 See Other>> |- |- |- |X |- |- |-
|<<http-304,304 Not Modified>> |X |X |- |- |- |- |-
|<<http-307,307 Temporary Redirect>> |X |X |X |X |X |X |X
|<<http-400,400 Bad Request>> |X |X |X |X |X |X |X
|<<http-401,401 Unauthorized>> |X |X |X |X |X |X |X
|<<http-403,403 Forbidden>> |X |X |X |X |X |X |X
|<<http-404,404 Not Found>> |X |X |X |X |X |X |X
|<<http-405,405 Method Not Allowed>> |X |X |X |X |X |X |-
|<<http-406,406 Not Acceptable>> |X |X |X |X |X |X |X
|<<http-409,409 Conflict>> |- |- |X |X |X |X |-
|<<http-412,412 Precondition Failed>> |- |- |X |X |X |X |-
|<<http-413,413 Payload Too Large >>|- |- |X |X |X |- |-
|<<http-415,415 Unsupported Media Type>> |X |X |X |X |X |X |X
|<<http-429,429 Too Many Requests>> |X |X |X |X |X |X |X
|<<http-,500 Internal Server Error>> |X |X |X |X |X |X |X
|<<http-502,502 Bad Gateway>> |X |X |X |X |X |X |X
|<<http-503,503 Service Unavailable>> |X |X |X |X |X |X |X


|===
8 changes: 8 additions & 0 deletions src/main/asciidoc/resources-document.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -445,6 +445,14 @@ or
|Not Found
|The resource does not exist and thus cannot be deleted.
|<<http-409,409>>
|Conflict
|A constraint on the resource is violated.
The resource could not be deleted because the request is in conflict with the current
state of the resource.
For example, a REST API may return this response code when a client tries to DELETE a non-empty store resource.
|===
====

Expand Down
5 changes: 4 additions & 1 deletion src/main/asciidoc/statuscodes.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -216,7 +216,10 @@ The server failed to fulfill an apparently valid request.
A 500 error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response, and hope to GET a different response.
|All:
<<GET,GET>>, <<HEAD,HEAD>>, <<POST,POST>>, <<PUT,PUT>>, <<PATCH,PATCH>>, <<DELETE,DELETE>>, <<OPTIONS,OPTIONS>>

|502 Bad Gateway
|** The 502 ("Bad Gateway") status code indicates that the server, while acting as a gateway or proxy, received an invalid response from an inbound server it accessed while attempting to fulfill the request.**
|All:
<<GET,GET>>, <<HEAD,HEAD>>, <<POST,POST>>, <<PUT,PUT>>, <<PATCH,PATCH>>, <<DELETE,DELETE>>, <<OPTIONS,OPTIONS>>

|[[http-503]]503 Service Unavailable
|**503 (“Service Unavailable”) indicates that the server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.**
Expand Down

0 comments on commit dd8ca3e

Please sign in to comment.