From b719cb01cf8364045973a6683a4a2158787030a8 Mon Sep 17 00:00:00 2001 From: Max Ong Zong Bao Date: Wed, 16 Jan 2019 05:49:28 +0800 Subject: [PATCH] docs: Updating the API best practices (#24112) 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. --- guide/english/rest-api/index.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/guide/english/rest-api/index.md b/guide/english/rest-api/index.md index 7739423688..b3ea509603 100644 --- a/guide/english/rest-api/index.md +++ b/guide/english/rest-api/index.md @@ -36,8 +36,16 @@ resources via hyperlinks. *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 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) * [HTTP status codes](https://httpstatuses.com/) * [Documenting APIs: A guide for technical writers](https://idratherbewriting.com/learnapidoc/) -