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框架。
rest api设计的一般原则的更多相关文章
- javascript的api设计原则
前言 本篇博文来自一次公司内部的前端分享,从多个方面讨论了在设计接口时遵循的原则,总共包含了七个大块.系卤煮自己总结的一些经验和教训.本篇博文同时也参考了其他一些文章,相关地址会在后面贴出来.很难做到 ...
- GOTO Berlin: Web API设计原则
在邮件列表和讨论区中有很多与REST和Web API相关的讨论,下面仅是我个人对这些问题的一些见解,并没有绝对的真理,InnoQ的首席顾问Oliver Wolf在GOTO Berlin大会上开始自己的 ...
- Atitit. Api 设计 原则 ---归一化
Atitit. Api 设计 原则 ---归一化 1.1. 叫做归一化1 1.2. 归一化的实例:一切对象都可以序列化/toString 通过接口实现1 1.3. 泛文件概念.2 1.4. 游戏行业 ...
- 优秀API设计的十大原则
优秀API设计的十大原则 2015-09-23 分类:编程开发.设计模式.首页精华暂无人评论 分享到:更多4 二十万年薪PHP工程师培养计划 成为被疯抢的Android牛人 风中叶讲Java重难 ...
- API设计原则
译序 Qt的设计水准在业界很有口碑,一致.易于掌握和强大的API是Qt最著名的优点之一.此文既是Qt官网上的API设计指导准则,也是Qt在API设计上的实践总结.虽然Qt用的是C++,但其中设计原则和 ...
- API设计原则(觉得太合适,转发做记录)
API设计原则 对于云计算系统,系统API实际上处于系统设计的统领地位,正如本文前面所说,K8s集群系统每支持一项新功能,引入一项新技术,一定会新引入对应的API对象,支持对该功能的管理操作,理解掌握 ...
- 好的框架需要好的 API 设计 —— API 设计的六个原则
说到框架设计,打心底都会觉得很大很宽泛,而 API 设计是框架设计中的重要组成部分.相比于有很多大佬都认可的面向对象的六大原则.23 种常见的设计模式来说,API 设计确实缺少行业公认的原则或者说设计 ...
- RESTful API设计原则与规范
RESTful API设计原则与规范 一.背景与基础概念 2 二.RESTful API应遵循的原则 3 1.协议(Protocol) 3 2.域名(ROOT URL) 3 3.版本(Versioni ...
- 【JS】327- javascript 的 api 设计原则
点击上方"前端自习课"关注,学习起来~ 前言 本篇博文来自一次公司内部的前端分享,从多个方面讨论了在设计接口时遵循的原则,总共包含了七个大块.系卤煮自己总结的一些经验和教训.本篇博 ...
随机推荐
- js生成一个以零开头的八位数并且依次递增
条件:1八位数:2.以领开头:3.末尾要依次递增 <script type="text/javascript">function Account(num,a){ // ...
- mssql禁用启用主键约束
EXEC sp_msforeachtable 'ALTER TABLE ? NOCHECK CONSTRAINT ALL' --禁用 EXEC sp_msforeachtable 'ALTER TA ...
- 获取实体属性名称(Property)和DisplayName属性名称(Attribute)
代码: public Dictionary<string, string> XXXModelColumnName { get { var dic = new Dictionary<s ...
- ngrok内网穿透利器在windws下的使用
1.到官网下载windows版本:https://ngrok.com/download 2.解压,双击“ngrok.exe” 3.输入“ngrok http 80”,会随机给你分配域名.见下图. ng ...
- TMS320C64X+ 中使用EDMA3中断
关于EDMA3,TI的文档有详细的介绍.园子里的文章 http://www.cnblogs.com/fpga/archive/2009/10/13/1582516.html,http://www.cn ...
- Job中织梦标签的调用
织梦CMS是一个好东东, 可以让一个网站更好维护和管理, 唯一让我感到忧桑的就是经常在搭后台的时候记不住那些标签,,无奈只能去看手册,有相同的案例直接COPY过来,直接用就OK~~~其实CMS这个东西 ...
- http request method and response codes
============================ HTTP_Method============================ HTTP Method Action Examples GET ...
- PHP CLI下接受参数的几种方法
PHP CLI(命令行模式下)接受参数有多种方法: (1)使用$argv接受参数 <?php //变量仅在 register_argc_argv 打开时可用. print_r($argc); / ...
- 【R】如何确定最适合数据集的机器学习算法 - 雪晴数据网
[R]如何确定最适合数据集的机器学习算法 [R]如何确定最适合数据集的机器学习算法 抽查(Spot checking)机器学习算法是指如何找出最适合于给定数据集的算法模型.本文中我将介绍八 ...
- CodeForces 353B Two Heaps
B. Two Heaps Valera has 2·n cubes, each cube contains an integer from 10 to 99. He arbitrarily cho ...