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框架。

上一篇:[OpenCV Qt教程] 如何在内存中压缩图像


下一篇:ActionScript3游戏中的图像编程(连载十七)