什么是 Restful API ?

RESTful API是目前比较成熟的一套互联网应用程序的API设计理论.

关注点说明
协议http / https
域名api.domain.com / domain.com/api/
版本api.domain.com/v1/ / 在 Request Header 中加入版本信息

设计步骤

第一步 、资源路径

一切均资源。所以，不能使用动词，一般都是用名词复数形式。如：users, posts.

第二步、HTTP动词的确定

动词说明
GET读取，取出资源
POST新建资源
PUT更新资源（全部修改）
PATCH更新资源（部分修改）
DELETE删除资源

第三步、过滤信息的设计

过滤解释
?limit=10限制条数
?offset=10指定读取位置
?page=1&per_page=20&sortBy=created_at&order=desc分页信息
other其他过滤信息

第四步、HTTP状态码

状态码解释说明
200OKGET请求成功
201CREATED资源创建成功或编辑成功
202Accepted资源处理已添加入队列
204NO CONTENT删除成功
400INVALID REQUEST用户请求错误(POST,PUT,PATCH)
401Unauthorized无权限
403Forbidden操作被禁止
404NOT FOUND记录不存在
406Not Acceptable用户请求的数据格式错误
422Unprocesable entity创建或编辑对象时未通过验证，如：用户名长度不符合
500INTERNAL SERVER ERROR服务器内部错误

第五步、错误处理

如果状态码是4xx信息，需要返回错误信息

JSON 格式数据，如：

{
    "error": "error information."
}

第六步、注意事项

  • 返回数据尽量使用 JSON 数据格式，避免使用 XML.
  • 用户授权采用 OAuth 2.0 协议.

实例

现在以 post 做个实例.以下是 RESTful API 设计：

版本，协议，域名不考虑.

URLMethod说明可以返回的状态码
/posts?{page=1&per_page=10&limit=10&offset=10}GET获取部分(所有)帖子200,404
/post/1GET获取ID为1的帖子200,404
/postPOST创建帖子201,202,400,401,403,406,422,500
/post/1DELETE删除ID为1的帖子204,401,403,404,500
/post/1PUT编辑ID为1的帖子201,202,400,401,403,406,422,500

项目实战

地址：https://github.com/Qsnh/CloudBookMark

文章目录