RESTful API接口设计规范
目录
- 一、RESTful的诞生背景
- 二、什么是RESTful?
- 三、Restful API接口设计规范
- 3.1、协议
- 3.2、路径规则|域名
- 3.3、版本控制
- 3.4、请求类型
- 3.5、传入参数
- 3.5.1、地址栏参数
- 3.5.2、请求body数据
- 3.5.3、请求头
- 3.6、返回格式
- 四、非 Restful Api 的需求
- 4.1、单例型:
- 4.2、组合型:
- 4.3、自定义组合API
一、RESTful的诞生背景
近年来移动互联网的发展,前端设备层出不穷(手机、平板、桌面电脑、其他专用设备…),因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信,于是RESTful诞生了,它可以通过一套统一的接口为 Web,iOS和Android提供服务。
二、什么是RESTful?
RESTful,简称REST。
1、英文:Representational State Transfer。
2、直译:表现层状态转化。
3、本质:用URL定位资源,用HTTP动词(GET,POST,DELETE,DETC)描述操作。
4、特点:RESTful是一种软件架构风格、设计风格,而不是标准,只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。 基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制。
5、设计原则和约束条件:
5.1、网络上的所有事物都可以被抽象为资源(resource);
5.2、每一个资源都有唯一的资源标识(resource identifier),对资源的操作不会改变这些标识;
5.3、所有的操作都是无状态的。
凡事满足这些约束条件和原则的应用程序或设计就是 RESTful。
6、通俗解释:服务器上每一种资源,比如一个文件,一张图片,一部电影,都有对应的唯一的url地址(URI:统一资源标识符),如果我们的客户端需要对服务器上的这个资源进行操作,就需要通过http协议(GET、POST、PUT、PATCH、DELETE)执行相应的动作来操作它,比如进行获取,更新,删除。
7、补充:
7.1、 在 RPC 样式的架构中,关注点在于方法,而在 REST 样式的架构中,关注点在于资源 —— 将使用标准方法检索并操作信息片段(使用表示的形式)。资源表示形式在表示形式中使用超链接互联。
7.2、关于http接口、api接口、RPC接口、RMI、webservice、Restful等概念。
三、Restful API接口设计规范
REST描述的是在网络中client和server的一种交互形式;REST本身不实用,实用的是如何设计 RESTful API(REST风格的网络接口)。
下面是根据Restful思想设计的通用规范:
3.1、协议
包含 http 和 https,使用 https 可以确保交互数据的传输安全。
3.2、路径规则|域名
路径又称 “终点”(endpoint),表示 API 的具体网址。
在 RESTful 架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的 “集合”(collection),所以 API 中的名词也应该使用复数。
包含两种形式:
a、主域名:https://api.example.com
b、子目录:https://example.org/api/
3.3、版本控制
版本号:v {n} n 代表版本号,分为整形和浮点型
整型:大功能版本发布形式;具有当前版本状态下的所有 API 接口,例如:v1,v2。
浮点型:为小版本号,只具备补充 api 的功能,其他 api 都默认调用对应大版本号的 api 例如:v1.1 v2.2。
放入位置:
1、将版本号放入URL中(方便直观)。
2、将版本号放在请求头。
3.4、请求类型
GET(SELECT):从服务器取出资源(一项或多项)。
POST(CREATE):在服务器新建一个资源。
PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
DELETE(DELETE):从服务器删除资源。
3.5、传入参数
3.5.1、地址栏参数
主要用于过滤查询
a、restful 地址栏参数 /api/v1/product/122 122 为产品编号,获取产品为 122 的信息
b、get 方式的查询字串,此种方式主要用于过滤查询,如下:
?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始位置。
?page=2&per_page=100:指定第几页,以及每页的记录数。
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序(sequence、order)。
?producy_type=1:指定筛选条件
3.5.2、请求body数据
主要用于提交新建数据
3.5.3、请求头
用于存放请求格式信息、版本号、token 密钥、语言等信息
{Accept: 'application/json', //json格式version: 'v1.0' //版本号Authorization: 'Bearer {access_token}', //认证tokenlanguage: 'zh' //语言
}
3.6、返回格式
默认返回格式:
{code: 0, //状态码msg: 'ok', //提示信息data: {} //主体数据
}
使用 json 格式作为响应格式,状态码分为两种:
a、statusCode: 系统状态码,用于处理响应状态,与 http 状态码保持一致,如:200 表示请求成功,500 表示服务器错误。
b、code:业务状态码,用于处理业务状态,一般 0 标识正常,可根据需求自行设计错误码对照表,参考
四、非 Restful Api 的需求
我们一般以 Restful Api 作为接口规范,但是由于实际业务开展过程中,可能会出现各种的 api 不是简单的 restful 规范能实现的,因此,需要有一些 api 突破 restful 规范原则。特别是移动互联网的 api 设计,更需要有一些特定的 api 来优化数据请求的交互。
4.1、单例型:
客户端根据需求分别请求对应 Api 接口,在客户端完成组装。
这种模式服务端相对简单,接口复用率高。
每个接口作用单一,如一个 App 首页,可能有轮播图、分类、推荐商品,则需要分别请求:
/api/v1/banners: 轮播
/api/v1/categories: 分类
/api/v1/product?is_recommend=1: 商品
开发过程中可根据实际需要结合使用。
4.2、组合型:
服务端组装数据,然后返回。
把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据,如:
api/v1/get-home-data 返回首页用到的所有数据
这类 API 有一个非常不好的地址,只要业务需求变动,这个 api 就需要跟着变更。
4.3、自定义组合API
把当前用户需要在第一时间内容加载的多个接口合并成一个请求发送到服务端,服务端根据请求内容,一次性把所有数据合并返回,相比于页面级API,具备更高的灵活性,同时又能很容易的实现页面级的API功能。
data:[{url:'api1',type:'get',data:{...}},{url:'api2',type:'get',data:{...}},{url:'api3',type:'get',data:{...}},{url:'api4',type:'get',data:{...}}
]
总结:
简单来说就是url地址中只包含名词表示资源,使用http动词表示动作进行操作资源.
下面几个例子:左边是错误的设计,而右边是正确的
GET /blog/getArticles --> GET /blog/Articles 获取所有文章
GET /blog/addArticles --> POST /blog/Articles 添加一篇文章
GET /blog/editArticles --> PUT /blog/Articles 修改一篇文章
GET /rest/api/deleteArticles?id=1 --> DELETE /blog/Articles/1 删除一篇文章
参考链接:
1、RESTful(百科)
2、网上整理的对于Rest和Restful api的理解
3、什么是RESTful API
4、API 接口设计规范
5、系统API接口规范
RESTful API接口设计规范相关推荐
- 整合swagger2生成Restful Api接口文档
整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...
- SpringMVC Restful api接口实现
[前言] 面向资源的 Restful 风格的 api 接口本着简洁,资源,便于扩展,便于理解等等各项优势,在如今的系统服务中越来越受欢迎. .net平台有WebAPi项目是专门用来实现Restful ...
- 无需编程,基于甲骨文oracle数据库零代码生成CRUD增删改查RESTful API接口
无需编程,基于甲骨文oracle数据库零代码生成CRUD增删改查RESTful API接口 回顾 通过之前一篇文章 无需编程,基于PostgreSQL零代码生成CRUD增删改查RESTful API接 ...
- RESTful API接口基本内容
RESTful API接口基本内容 目录 RESTful API接口基本内容 一.RESTful是什么? 1.1.基本特点 1.2.设计概念和准则 1.3.http协议 二.RESTful与SOAP ...
- API 接口设计规范
概述 这篇文章分享 API 接口设计规范,目的是提供给研发人员做参考. 规范是死的,人是活的,希望自己定的规范,不要被打脸. 路由命名规范 动作 前缀 备注 获取 get get{XXX} 获取 ge ...
- Restful API是什么?初探Restful API,传统接口写法与Restful API接口写法区别
Restful API是什么?初探Restful API?为什么要用Restful API?传统接口写法与Restful API接口写法区别,带着这些问题我们来具体了解下Restful API: 目录 ...
- swagger php 生成api,blog/Swagger生成php restful API接口文档.md at master · lfq618/blog · GitHub...
Swagger生成php restful API接口文档 背景 我们的restful api项目采用yaf框架, 整体结构简单, 我们只需要用swagger扫描 application目录即可. 下面 ...
- 无需编程,基于微软mssql数据库零代码生成CRUD增删改查RESTful API接口
无需编程,基于微软mssql数据库零代码生成CRUD增删改查RESTful API接口 回顾 通过之前一篇文章 无需编程,基于甲骨文oracle数据库零代码生成CRUD增删改查RESTful API接 ...
- restful url 设计规范_RESTful API接口设计规范
网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备-).因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信.这导致API构架的流行 ...
最新文章
- Windows 10 Anaconda Python 3.7 安装 MXNet GPU版
- 硬核!如何模拟 5w+ 的并发用户?
- 从零开始入门 K8s | K8s 安全之访问控制
- 抓取html 中文乱码,利用代码抓取网页数据,出现中文乱码问题
- ArcGIS之通过Model Builder执行地理处理
- 手机相机里面的m_传玉晶光担任新款iphone后置相机广角、超广角镜头主要供应商...
- vs 警告被视为错误
- C++基础::STL中的定理
- Median of Two Sorted Arrays@LeetCode
- 慕课PDF下载扩展--再也不用担心慕课不给PDF了
- 夯实Java基础系列8:深入理解Java内部类及其实现原理
- 图像分割——meanshift算法(C++GDAL库)
- 四季芬芳,花开不只在春天
- Windows与网络基础-27-子网掩码
- Nat. Med. :婴儿生命早期肠道病毒组和细菌组的动态
- 圆角半角数据库_MySQL存储全角字符和半角字符的区别
- 佛说爱情二:前生500次的回眸才换得今生的一次擦肩而过
- python学习三-基础语法
- 在word的文字右上角添加符号(插入上标)?
- 数据结构——二叉搜索树
热门文章
- 程序清单5.3_golf.c程序_《C Primer Plus》P90
- 【python实操】马上毕业了,你还不懂什么是守护线程、线程、进程?(附12306抢票程序-源代码)
- NIO(一)--简介API介绍
- android应用的自启动 和 相互关联启动
- 使用MJExtension进行字典模型转换
- 循序渐进BootstrapVue,开发公司门户网站(5)--- 使用实际数据接口代替本地Mock数据
- 工业4.0区块链Startup 05
- MIO神达A700/A701ROM刷机教程
- 淘宝、天猫用的Android框架V-Layout,赶紧收藏
- 图片转.eps格式的方法