RESTful API 编写规范

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:从服务器获取报头信息（不是资源）。