一、域名
将 api 部署在专用域名下:http://api.example.com。
或者将 api 放在主域名下:http://www.example.com/api/。
二、版本
将 API 的版本号放在 url 中。http://www.example.com/app/1.0/info。
三、路径
路径表示 API 的具体网址。每个网址代表一种资源。 资源作为网址,网址中不能有动词只能有名词, 一般名词要与数据库的表名对应。而且名词要使用复数。
错误示例:http://www.example.com/getGoods
http://www.example.com/listOrders
正确示例: #获取单个商品 http://www.example.com/app/goods/1
#获取所有商品 http://www.example.com/app/goods
四、使用标准的 HTTP 方法
对于资源的具体操作类型,由 HTTP 动词表示。 常用的 HTTP 动词有四个。
- GET SELECT :从服务器获取资源。
- POST CREATE :在服务器新建资源。
- PUT UPDATE :在服务器更新资源。
- DELETE DELETE :从服务器删除资源。
示例:
#获取指定商品的信息 GET http://www.example.com/goods/ID
#新建商品的信息 POST http://www.example.com/goods
#更新指定商品的信息 PUT http://www.example.com/goods/ID
#删除指定商品的信息 DELETE http://www.example.com/goods/ID
五、过滤信息
如果资源数据较多,服务器不能将所有数据一次全部返回给客户端。
API 应该提供参数,过滤返回 结果。
实例:
#指定返回数据的数量 http://www.example.com/goods?limit=10
#指定返回数据的开始位置 http://www.example.com/goods?offset=10
#指定第几页,以及每页数据的数量 http://www.example.com/goods?page=2&per_page=20
六、状态码
服务器向用户返回的状态码和提示信息,
常用的有:
200 OK :服务器成功返回用户请求的数据
201 CREATED :用户新建或修改数据成功。
202 Accepted:表示请求已进入后台排队。
400 INVALID REQUEST :用户发出的请求有错误。
401 Unauthorized :用户没有权限。
403 Forbidden :访问被禁止。
404 NOT FOUND :请求针对的是不存在的记录。
406 Not Acceptable :用户请求的的格式不正确。
500 INTERNAL SERVER ERROR :服务器发生错误。
七、错误信息
一般来说,服务器返回的错误信息,以键值对的形式返回。
{
error:'Invalid API KEY'
}
八、响应结果:
针对不同结果,服务器向客户端返回的结果应符合以下规范。
#返回商品列表 GET http://www.example.com/goods
#返回单个商品 GET http://www.example.com/goods/cup
#返回新生成的商品 POST http://www.example.com/goods
#返回一个空文档 DELETE http://www.example.com/goods
九、使用链接关联相关的资源
在返回响应结果时提供链接其他 API 的方法,使客户端很方便的获取相关联的信息。
十、其他
服务器返回的数据格式,应该尽量使用 JSON,避免使用 XML。