rest api设计的一般原则

本文参考自：http://www.ruanyifeng.com/blog/2014/05/restful_api.html,http://www.dongming8.cn/?p=590

服务器端：

1. JSON形式：

请求method	含义	api建议格式(url) v1-版本号，	成功返回值	失败码(典型)	备注
PUT	修改数据请求 (客户端提供改变后的完整资源)	/v1/collection/ID	完整的对象信息(JSON格式)	201(Updated) 403(Forbidden) 500(ServerError)
POST	创建数据请求	/v1/collection/ID	新创建的完整的对象信息(JSON格式)	201(Created) 403(Forbidden) 500(ServerError)
DELETE	删除数据请求	/v1/collection/ID	空文档	403(Forbidden) 500(ServerError)
GET	读取数据请求	/v1/collection/ID or  /v1/collection/?limit=n?offset=10?page=2&per_page=100?sortby=name&order=asc?animal_type_id=1	单个资源对象 or 资源对象的列表（数组）	200(OK) 404(NotFound) 410(Gone)
PATCH	修改数据请求 （客户端提供改变的属性）	/v1/collection/ID	完整的对象信息(JSON格式)	201(Updated) 403(Forbidden) 500(ServerError)
以下比较少用到
HEAD	获取资源的元数据
OPTIONS	获取信息， 客户端可修改属性集。

 

可发现性(discoverability)

无论成功还是失败，最好附有一个link字段，用于标注相关的api，提示用户下一步可以做什么，如下：

{

"link": {
  "rel":   "collection https://www.example.com/zoos",//这个API与当前网址的关系
  "href":  "https://api.example.com/zoos",//api地址
  "title": "List of zoos",//api标题
  "type":  "application/vnd.yourformat+json"//api返回值类型
}

}

错误返回消息的一般格式：

{
   'code':1234,//错误代码
   'message':'错误消息',
   'descrpition':'详细信息',//简单描述，可用于GET/DELETE请求。或者以下字段
   'errors'://用于更详细的针对栏位的提示，通常用于POST/PATCH/PUT请求
    [
       {
           'code':3122,//代码
           'field':'具体字段',
           'message':'具体原因',
        },
        ...
    ]
}

当然，也应该根据具体情况具体定义格式。　　

错误消息应当以200的状态码返回么？不应该，参考这里。

当发生错误的时候，通常正常的返回对应的状态码。

补充：

API与用户的通信协议，总是使用HTTPs协议。

API的身份认证应该使用OAuth 2.0框架。