gaspersic/freeCodeCamp
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: Updating the API best practices (#24112)

Browse Source 
Added the API URL design to include versioning and limiting the use of PUT requests to only updating of existing records instead of allowing the creation of new records using PUT request.
This commit is contained in:
Max Ong Zong Bao
2019-01-16 05:49:28 +08:00
committed by Christopher McCormack
parent 7375637d58
commit b719cb01cf
1 changed files with 9 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
guide/english/rest-api/index.md
View File

@ -36,8 +36,16 @@ resources via hyperlinks.
*Note while PUT operations either client or server can generate id's* *Note while PUT operations either client or server can generate id's*
- #### Nouns are good, Verbs are bad - #### Versioning as Part of URL Design
- Use the prefix **V#** to indicate the version of your URL like `api/v1/people` or `api/V2/people`.
- Never use a dot notion as prefix like `api/v1.2/people` to indiate your version. By doing that it will confuse the developer using the API. When there is frequent updates or depreciation of API versions.
- #### Limiting PUT and POST requests
- Due to similarity of PUT to POST operation, which could be easily exploited to create a new record.
- Use POST requests to **create** records, whereas PUT request to be **updating** of existing records.
- Create a checker function to check for PUT request that is used to **create** new records.
- #### Nouns are good, Verbs are bad
- Use nouns to refer resources like `cars`, `fruits` etc. - Use nouns to refer resources like `cars`, `fruits` etc.
- Use verbs for action declarations `convertMilesToKms`, `getNutritionalValues` - Use verbs for action declarations `convertMilesToKms`, `getNutritionalValues`
@ -141,4 +149,3 @@ A detailed explanation has been given on Quick Code blog on how to use Postman f
* [The never-ending REST API design debate by Guillaume Laforge](https://www.youtube.com/watch?v=48azd2VqtP0) * [The never-ending REST API design debate by Guillaume Laforge](https://www.youtube.com/watch?v=48azd2VqtP0)
* [HTTP status codes](https://httpstatuses.com/) * [HTTP status codes](https://httpstatuses.com/)
* [Documenting APIs: A guide for technical writers](https://idratherbewriting.com/learnapidoc/) * [Documenting APIs: A guide for technical writers](https://idratherbewriting.com/learnapidoc/)