本文参考自：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框架。