REST全称是Representational State Transfer,表述状态转移的意思。它是在Roy Fielding博士论文首次提出。REST本身没有创造新的技术、组件或服务,它的理念就是在现有的技术之上,更好的使用现有的 web规范。用REST规范的web服务器,能够更好的展现资源,客户端能够更好的使用资源。每个资源都由URI/ID标识。REST本身跟http无关,但是目前http是与它相关的唯一实例。REST有着优雅、简洁的特性,本文是根据豆瓣api来谈谈自己对restful的一些理解。
URI 的格式:
URI的格式定义如下:
URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]
比如
https://api.douban.com/v2
"/"分隔符一般用来对资源层级的划分,比如:
https://api.douban.com/v2/book/1220562
表述了豆瓣api,version2下的图书仓库下的编号为1220562的图书。
比如 豆瓣图书api:
name | method | api |
---|---|---|
获取图书信息 | get | /v2/book/:id |
用户收藏某本图书 | post | /v2/book/:id/collection |
用户修改对某本图书的收藏 | put | /v2/book/:id/collection |
用户删除对某个图书的收藏 | delete | /v2/book/:id/collection |
http请求需要返回状态码,约定俗成的状态码能够帮助开发团队提高沟通效率。
比如豆瓣api返回的状态码说明:
状态码 | 含义 | 说明 |
---|---|---|
200 | ok | 请求成功 |
201 | created | 创建成功 |
202 | accepted | 更新成功 |
400 | bad request | 请求不存在 |
401 | unauthorized | 未授权 |
403 | forbidden | 禁止访问 |
404 | not found | 资源不存在 |
500 | internal server error | 内部错误 |
通用错误码,具体产品由具体产品api给出。比如豆瓣api:
错误码 | 错误信息 | 含义 |
---|---|---|
999 | unknow_v2_error | 未知错误 |
1000 | need_permission | 需要权限 |
1001 | uri_not_found | 资源不存在 |
… | …. | … |
太多了,只列出几条,具体见豆瓣 api。
这部分内容不属于这篇文章,但是稍微说明下:
接口文档的编写至关重要,最好是写一个在线接口文档。接口文档能够方便团队查阅,减少不必要的沟通。如果对外公开api,api文档的质量直接反应了一个公司的技术水平,甚至一个公司的文化气质。
本文参考了以下的资料: