Restful API介面規範

REST：英文representational state transfer直譯為表現層狀態轉移，或者表述性狀態轉移；Rest是web服務的一種架構風格，一種設計風格，是一種思想；同時Rest不是針對某一種程式語言的。

以webService為例通俗解釋。

非Rest設計，以往我們都會這麼寫：

http://localhost:8080/admin/getUser（查詢使用者）

http://localhost:8080/admin/addUser（新增使用者）

http://localhost:8080/admin/updateUser（更新使用者）

http://localhost:8080/admin/deleteUser

總結：以不同的URL（主要為使用動詞）進行不同的操作。

Rest架構：

GEThttp://localhost:8080/admin/user（查詢使用者）

POSThttp://localhost:8080/admin/user（新增使用者）

PUThttp://localhost:8080/admin/user（更新使用者）

DELETEhttp://localhost:8080/admin/user（刪除使用者）

總結：URL只指定資源，以HTTP方法動詞進行不同的操作。用HTTP STATUS/CODE定義操作結果。

Restful：遵守了rest風格的web服務便可稱為Restful。

為什麼需要Restful？

URL具有很強可讀性的，具有自描述性

規範化請求過程和返回結果

資源描述與檢視的鬆耦合

可提供OpenAPI，便於第三方系統整合，提高互操作性

提供無狀態的服務介面，降低複雜度，可提高應用的水平擴充套件性

/版本號/資源路徑

/v1/tags/{tag_id}

/v1/users?[&keyword=xxx][&enable=1][&offset=0][&limit=20]

1、版本號

命名版本號可以解決版本不相容問題，在設計 RESTful API 的一種實用的做法是使用版本號。一般情況下，我們會在 url 中保留舊版本號，並同時相容多個版本

【GET】 /v1/users/{user_id} // 版本 v1 的查詢使用者列表的 API 介面

【GET】 /v2/users/{user_id} // 版本 v2 的查詢使用者列表的 API 介面

2、資源路徑

URI 不能包含動詞，只能是名詞（命名名詞的時候，要使用小寫、數字及下劃線來區分多個單詞）。

資源的路徑應該從根到子依次如下:

/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}

【POST】 /v1/users/{user_id}/roles/{role_id} // 新增使用者的角色

有的時候，當一個資源變化難以使用標準的 RESTful API 來命名，可以考慮使用一些特殊的 actions 命名。

/{resources}/{resource_id}/actions/{action}

【PUT】 /v1/users/{user_id}/password/actions/modify // 密碼修改

3、請求方式

【GET】 /users # 查詢使用者資訊列表

【GET】 /users/1001 # 檢視某個使用者資訊

【POST】 /users # 新建使用者資訊

【PUT】 /users/1001 # 更新使用者資訊(全部欄位)

【PATCH】 /users/1001 # 更新使用者資訊(部分欄位)

【DELETE】 /users/1001 # 刪除使用者資訊

【PATCH】一般不用，用【PUT】

4、查詢引數

RESTful API 介面應該提供引數，過濾返回結果。

【GET】 /{version}/{resources}/{resource_id}?offset=0&limit=20

5、響應引數

JSON格式（code、data、msg）

6、狀態碼

使用適合的狀態碼很重要，而不應該全部都返回狀態碼 200

狀態碼，可根據以下標準按照專案擴充套件自身狀態碼：

200~299段 表示操作成功：

200 操作成功，正常返回

201 操作成功，已經正在處理該請求

300~399段 表示引數方面的異常

300 引數型別錯誤

301 引數格式錯誤

302 引數超出正常取值範圍

303 token過期

304 token無效

400~499段 表示請求地址方面的異常：

400 找不到地址

500~599段 表示內部程式碼異常：

500 伺服器程式碼異常

7、完整事例

UserController.java

@RestController(/v1)

@API(tag=”使用者相關介面”)

public class UserController {
 

    @Autowired

    private UserJPARepository userJPARepository;


    /**

     * 查詢使用者列表

     * @return

     */

    @GetMapping(value = "/user")

    public List<User> findUserList(){

        return userJPARepository.findAll();

    }


    /**

     * 根據Id查詢一個使用者

     * @param id

     * @return

     */

    @GetMapping(value = "/user/query/{id}")

    public User findUserOne(@PathVariable("id") Integer id){

        return userJPARepository.findOne(id);

    }


    /**

     * 新增使用者

     * @param name

     * @param age

     * @param country

     * @return

     */


    @PostMapping(value = "/user")

    public User addUser(@RequestParam("name") String name, @RequestParam("age") int age,

                        @RequestParam("country") String country){

        User user = new User();

        user.setName(name);

        user.setAge(age);

        user.setCountry(country);

        return userJPARepository.save(user);

    }

    /**

     * 刪除使用者

     * @param id  使用者編號

     * @return

     */

    @DeleteMapping(value = "/user/{id}")

    public  List<User> deleteUser(@PathVariable("id") Integer id){

        userJPARepository.delete(id);

        return userJPARepository.findAll();

    }

    /**

     * 更新使用者

     * @param id

     * @param name

     * @param age

     * @param country

     * @return

     */

    @PutMapping(value = "/user/{id}")

    public User updateUser(@PathVariable("id") Integer id, @RequestParam("name") String name,

                           @RequestParam("age") int age, @RequestParam("country") String country){

        User user = userJPARepository.findById(id);

        user.setName(name);

        user.setAge(age);

        user.setCountry(country);

        return userJPARepository.save(user);

    }

    /**

     * 根據國家查詢使用者

     * @param country

     * @return

     */

    @GetMapping(value = "/user/{country}")

    public List<User> findByCountry(@PathVariable("country") String country){

        return userJPARepository.findByCountry(country);

    }

}