Cleaned up some of my notes on REST, since I was reading up on this, more might come

Author: jonasbn

README.md

@@ -805,6 +805,8 @@
 - [Use proper headers](rest/use_proper_headers.md)
 - [Check out OpenAPI](rest/check_out_openapi.md)
 - [Use verbs](rest/use_verbs.md)
+- [Deprecating API Endpoints](rest/deprecating_api_endpoints.md)
+- [Notes on RESTful API design](rest/notes_on_restful_api_design.md)
 
 <a id="rm"></a>
 ### rm - remove files and directories on the command line

rest/deprecating_api_endpoints.md

@@ -0,0 +1,32 @@
+# Deprecating API endpoints
+
+As for deprecation indication using HTTP status code there is no clear specification.
+
+Various answers on StackOverflow and the like tend towards: `410 Gone`.
+
+Some suggest using: `301 Moved Permanently` or `302 Found`.
+
+I do see some challenges with: `401` as it should indicate that the resource pointed to no longer exists.
+
+I believe the HTTP status code: `501 Not implemented` could be used but is not the best solution BUT it could be combined with redirects. Alternatively: `405 Not Allowed` might be a better and with better control with assistance: `Allow` header to solve this:
+
+- You have an API and a resource which can be fetched via: `GET`, it would normally return the resource and the HTTP status code: `200 Ok`
+  - if the resource was deleted you should return: `410 Gone`
+- If the API is deprecated one could return `308 Permanent Redirect` for a period of time indicating the replacement via the `Location` header, like a newer version: `/api/v1` to `/api/v2` and this would work for both: `POST` and `GET` where `301 Moved Permanently` only works for `GET`
+  - If no replacement is in available return: `405 Not Allowed`
+- In due time and after adoption have been made for the new API endpoint, use: `405 Not Allowed` since the API endpoint is gone and it will not come back
+
+For the Swagger part, do see my TIL on that:
+
+- [Deprecating API endpoints](../swagger/deprecating_api_endpoints.md)
+
+## Resources and References
+
+- [MDN: HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status)
+- [MDN: 301 Moved Permanently](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/301)
+- [MDN: 302 Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/302)
+- [MDN: 308 Permanent Redirect](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/308)
+- [MDN: 405 Method Not Allowed](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/405)
+- [MDN: 410 Gone](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/410)
+- [MDN: 501 Not Implemented](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/501)
+- [StackOverflow: "What is the correct HTTP status code for: "This version of this API has been discontinued"?](https://webmasters.stackexchange.com/questions/71152/what-is-the-correct-http-status-code-for-this-version-of-this-api-has-been-dis)

rest/notes_on_restful_api_design.md

@@ -0,0 +1,30 @@
+# Notes on RESTful API Design
+
+This is a list of return codes in relation to a RESTful API design.
+
+Some of the operations has more that one outcome, so you need to decide on what you find the most appropriate one.
+
+<table>
+<tr><th>Operation</th><th>HTTP Method</th><th>STATUS CODE ON SUCCESS</th></tr>
+<tr><td>Create</td><td>POST</td><td>201 Created</td></tr>
+<tr><td></td><td></td><td>202 Accepted</td></tr>
+<tr><td>Read</td><td>GET</td></td><td>200 OK</td></tr>
+<tr><td rowspan=4>Update</td><td rowspan=2>PUT</td><td>200 OK</td></tr>
+<tr><td>204 No Content</td></tr>
+<tr><td rowspan=2>PATCH</td><td>200 OK</td></tr>
+<tr><td>204 No Content</td></tr>
+<tr><td rowspan=3>Delete</td><td rowspan=3>DELETE</td><td>200 OK</td></tr>
+<tr><td>202 Accepted</td></tr>
+<tr><td>204 No Content</td></tr>
+</table>
+
+<table>
+<tr><th>Operation</th><th>HTTP Method</th><th>STATUS CODE ON ERROR</th></tr>
+<tr><td rowspan=2>Create</td><td rowspan=2>POST</td><td>409 Conflict</td></tr>
+<tr><td>422 Unprocessable Content</td></tr>
+<tr><td>Read</td><td>GET</td></td><td>404 Not Found</td></tr>
+<tr><td rowspan=3>Update</td><td rowspan=2>PUT</td><td>404 Not Found</td></tr>
+<tr><td>409 Conflict</td></tr>
+<tr><td>PATCH</td><td>404 Not Found</td></tr>
+<tr><td>Delete</td><td>DELETE</td><td>404 Not Found</td></tr>
+</table>

rest/use_verbs.md

@@ -1,21 +1,28 @@
 # Use Verbs
 
-Use the verbs specified for the HTTP protocol to get the most our of you HTTP based API.
+Use the _verbs_ specified for the HTTP protocol to get the most our of you HTTP based API.
+
+The _verbs_ are more correctly named: HTTP request methods and the term _verbs_ is also widely used.
 
 - `POST` for creation
 - `GET` for reading
-- `PUT` for updating or replacing
-- `PATCH` for updating or modifying
+- `PUT` for complete updating or replacing
+- `PATCH` for partial updating or modifying
 - `DELETE` for deletion
 
-If you, _like me_ cannot remember, which of the verbs does what, like `POST` and `PUT` you can use these simple rules of thumb, the first one I got from a colleague:
+If you, _like me_ cannot remember, which of the _verbs_ does what, like `POST`, `PUT` and `PATCH` you can use these simple rules of thumb, the first one I got from a colleague:
 
 > The `U` in `PUT` is for _update_
 
 And now for one I had to make for myself:
 
-> Post is always delivered at the gate, so when thinking about `POST`, remember gate rhymes with _create_
+> Post is always delivered at the gate, so when thinking about `POST`, remember gate rhymes with _create_...
+
+And the last one is for `PATCH`, if you are RESTful
+
+> `PATCH` can do a partial update compared to `PUT` so "PAT" is short for _partial_...
 
-## Resources
+## Resources and References:
 
 - [RestApiTutorial.com](https://www.restapitutorial.com/lessons/httpmethods.html)
+- [MDN: HTTP Request Methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods)

swagger/deprecating_api_endpoints.md

@@ -8,7 +8,9 @@ For alternative rendering of a deprecated endpoint, the flag: `deprecated` can b
 }
 ```
 
-TODO: Write more about other deprecation approaches
+For more information on the RESTful part, have a look at my TIL:
+
+- [Deprecating API Endpoints](../rest/deprecating_api_endpoints.md)
 
 ## Resources and References