rest api设计的一般原则
2015-01-13 11:09
253 查看
本文参考自:http://www.ruanyifeng.com/blog/2014/05/restful_api.html,http://www.dongming8.cn/?p=590
服务器端:
1. JSON形式:
可发现性(discoverability)
无论成功还是失败,最好附有一个link字段,用于标注相关的api,提示用户下一步可以做什么,如下:
错误返回消息的一般格式:
当然,也应该根据具体情况具体定义格式。
错误消息应当以200的状态码返回么?不应该,参考这里。
当发生错误的时候,通常正常的返回对应的状态码。
补充:
API与用户的通信协议,总是使用HTTPs协议。
API的身份认证应该使用OAuth 2.0框架。
服务器端:
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 | 获取信息, 客户端可修改属性集。 | ||||
无论成功还是失败,最好附有一个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框架。
相关文章推荐
- 优秀REST风格 API的设计原则
- API设计原则
- 数据库设计--使用上述四种模式的一般原则(转)
- API通用设计原则
- 移动App的REST API设计实践
- REST API初识及设计
- 设计模式的一般原则
- HTTP API 设计指南(中文版) restfull
- REST简介及设计原则
- 设计原则:小议 SPI 和 API
- SQL数据库一般设计原则(一)
- 站点设计的一般原则
- 设计模式遵循的一般原则
- API设计原则
- C语言函数设计的一般原则和技巧
- 网页标题设计原则与一般规律
- API设计原则学习笔记
- 函数设计的一般原则和技巧
- 如何查看我的订单-REST的流程API设计案例
- C语言函数设计的一般原则和技巧