RESTful API 編寫規範

在一個RESTful系統裡，客戶端向服務端發起索取資源的操作只能通過HTTP協議語義來進行互動。最常用的HTTP協議語義有以下5個：

GET

GET:傳送一條或者多條GET請求都不會改變伺服器裡面的資源，同一個request發一遍和發兩遍都將獲得相同結果。這個互動行為是冪等的。
GET:從伺服器取出資源（一項或多項）

@ApiOperation(value="獲取使用者列表", notes="")
@RequestMapping(value={""}, method=RequestMethod.GET)
public List<User> getUserList() {
    List<User> r = new ArrayList<User>(users.values());
    return r;
}

@ApiOperation(value="獲取使用者詳細資訊", notes="根據url的id來獲取使用者詳細資訊")
@ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "Long")
@RequestMapping(value="/{id}", method=RequestMethod.GET)
public User getUser(@PathVariable Long id) {
    return users.get(id);
}

 

POST

POST:傳送的POST請求中會包含希望建立的新資源。收到POST請求後，伺服器會新增資源。這個互動行為是非冪等的。
POST：在伺服器新建一個資源

@ApiOperation(value="建立使用者", notes="根據User物件建立使用者")
@ApiImplicitParam(name = "user", value = "使用者詳細實體user", required = true, dataType = "User")
@RequestMapping(value="", method=RequestMethod.POST)
public String postUser(@RequestBody User user) {
    users.put(user.getId(), user);
    return "success";
}

 

PUT

PUT:客戶端傳送PUT請求對資源進行修改 (更新），此時服務端的資源發生變化，這種請求是冪等的。
PUT:在伺服器更新資源（客戶端提供完整資源資料）。

@ApiOperation(value="更新使用者詳細資訊", notes="根據url的id來指定更新物件，並根據傳過來的user資訊來更新使用者詳細資訊")
@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "Long"),
        @ApiImplicitParam(name = "user", value = "使用者詳細實體user", required = true, dataType = "User")
})

@RequestMapping(value="/{id}", method=RequestMethod.PUT)
public String putUser(@PathVariable Long id, @RequestBody User user) {
    User u = users.get(id);
    u.setName(user.getName());
    u.setAge(user.getAge());
    users.put(id, u);
    return "success";
}

 

DELETE

DELETE:傳送Delete請求之後，服務端資源將消失。當再次傳送一條Delete請求，客戶端獲得的資源狀態和第一次傳送Delete請求後的狀態是一致的。這個請求是冪等的。
DELETE:從伺服器刪除資源

@ApiOperation(value="刪除使用者", notes="根據url的id來指定刪除物件")
@ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "Long")
@RequestMapping(value="/{id}", method=RequestMethod.DELETE)
public String deleteUser(@PathVariable Long id) {
    users.remove(id);
    return "success";
}

HEAD

HEAD:當不知道使用何種請求方式獲取客戶 端資源時，可以使用HEAD方式，此時客戶端返回的不是具體的資源資訊，只是HTTP狀態碼和報頭。此方式是冪等的.
HEAD:從伺服器獲取報頭資訊（不是資源）。