restfull api 接口 规范
restfull api 接口 规范
1 这种接口 可以根据客户端 的要求类型返回不同的类型的 表现形式,比如返回json,返回xml,返回纯文本。
2 这种接口 不同的操作就得用不同的方法 get post delete put
GET(SELECT):从服务器取出资源(一项或多项)。
- POST(CREATE):在服务器新建一个资源。
- PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
- PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
- DELETE(DELETE):从服务器删除资源。
还有两个不常用的HTTP动词。
- HEAD:获取资源的元数据。
- OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。
3 这种接口不可以在 url 中 出现动词。
4 这种接口版本信息应该放到头文件中。
5 可以根据条件过滤信息:
如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。
下面是一些常见的参数。
- ?limit=10:指定返回记录的数量pi
- ?offset=10:指定返回记录的开始位置。
- ?page=2&per_page=100:指定第几页,以及每页的记录数。
- ?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
- ?animal_type_id=1:指定筛选条件
6 状态码:
服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词)。
- 200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
- 201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
- 202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
- 204 NO CONTENT - [DELETE]:用户删除数据成功。
- 400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
- 401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
- 403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
- 404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
- 406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
- 410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
- 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
- 500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
7 错误处理:
如果状态码是4xx,就应该向用户返回出错信息。一般来说,返回的信息中将error作为键名,出错信息作为键值即可。
{
error: "Invalid API key"
}
8返回结果:
针对不同操作,服务器向用户返回的结果应该符合以下规范。
- GET /collection:返回资源对象的列表(数组)
- GET /collection/resource:返回单个资源对象
- POST /collection:返回新生成的资源对象
- PUT /collection/resource:返回完整的资源对象
- PATCH /collection/resource:返回完整的资源对象
- DELETE /collection/resource:返回一个空文档
9 连接api
RESTful API最好做到Hypermedia,即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么。
比如,当用户向api.example.com的根目录发出请求,会得到这样一个文档。
{"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}
上面代码表示,文档中有一个link属性,用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系(collection关系,并给出该collection的网址),href表示API的路径,title表示API的标题,type表示返回类型。
Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计,访问api.github.com会得到一个所有可用API的网址列表。
{
"current_user_url": "https://api.github.com/user",
"authorizations_url": "https://api.github.com/authorizations",
// ...
}
从上面可以看到,如果想获取当前用户的信息,应该去访问api.github.com/user,然后就得到了下面结果。
{
"message": "Requires authentication",
"documentation_url": "https://developer.github.com/v3"
}
上面代码表示,服务器给出了提示信息,以及文档的网址。
10 其他:
(1)API的身份认证应该使用OAuth 2.0框架。
(2)服务器返回的数据格式,应该尽量使用JSON,避免使用XML。
11 无状态性:
RESTful只要维护资源的状态,而不需要维护客户端的状态。对于它来说,每次请求都是全新的,它只需要针对本次请求作相应的操作,不需要将本次请求的相关信息记录下来以便用于后续来自相同客户端请求的处理。
对于上面我们介绍的RESTful的这些个特性,它们都是要求我们为了满足这些特征做点什么,唯有这个无状态却是要求我们不要做什么,因为HTTP本身就是无状态的。举个例子,一个网页通过调用Web API分页获取符合查询条件的记录。一般情况下,页面导航均具有“上一页”和“下一页”链接用于呈现当前页的前一页和后一页的记录。那么现在有两种实现方式返回上下页的记录。
- Web API不仅仅会定义根据具体页码的数据查询定义相关的操作,还会针对“上一页”和“下一页”这样的请求定义单独的操作。它自身会根据客户端的Session ID对每次数据返回的页面在本地进行保存,以便能够知道上一页和下一页具体是哪一页。
- Web API只会定义根据具体页码的数据查询定义相关的操作,当前返回数据的页码由客户端来维护。
第一种貌似很“智能”,其实就是一种画蛇添足的作法,因为它破坏了Web API的无状态性。设计无状态的Web API不仅仅使Web API自身显得简单而精炼,还因减除了针对客户端的“亲和度(Affinty)”使我们可以有效地实施负载均衡,因为只有这样集群中的每一台服务器对于每个客户端才是等效的。
restfull api 接口 规范相关推荐
- RESTful API接口文档规范小坑
希望给你3-5分钟的碎片化学习,可能是坐地铁.等公交,积少成多,水滴石穿,谢谢关注. 前后端分离的开发模式,假如使用的是基于RESTful API的七层通讯协议,在联调的时候,如何避免配合过程中出现问 ...
- API接口通讯参数规范(2)
针对[API接口通讯参数规范]这篇文章留下的几个问题进行探讨. 问题1 试想一下,如果一个http请求返回一个500给我们,那我们是不是都不用看详情都知道该次请求发生了什么?这正是一个标准的结果码意义 ...
- 【编程规范】 后端API接口设计编写与文档编写参考
文章目录 0 统一规范 0.1 理清业务流程 0.2 定义前后端开发的接口规范 0.3 定义接口文档 1 后端接口编写 1.0 后端接口介绍 1.0.1 接口交互 1.0.2 返回格式 1.0.3 C ...
- Drf从入门到精通一(API接口、Postman、Restful规范、序列化、快速使用drf、CBV源码分析)
文章目录 一.前后端开发模式 二.API接口 三.接口测试工具Postman 四.Restful规范 五.序列化反序列化 六.DjangoRestFramework快速使用 七.CBV源码分析 一.前 ...
- Swagger3 API接口文档规范课程(Java1234)(内含教学视频+源代码)
Swagger3 API接口文档规范课程(Java1234)(内含教学视频+源代码) 教学视频+源代码下载链接地址:https://download.csdn.net/download/weixin_ ...
- Android开发规范:API接口安全设计规范
公众号[国民程序员]回馈粉丝福利: 现金红包和送书活动火热进行中,点击参与! 我的新书<Android App开发入门与实战>已于2020年8月由人民邮电出版社出版,欢迎购买. 书籍详情请 ...
- 大厂对外提供的API接口入参命名规范
最近查阅百度API接口时,发现接口文档中,参数明文居然是下划线格式,很疑惑.进一步查阅了 阿里开发平台.腾讯微信开发者平台, 对外api接口都是下划线命名, 为什么? java实体类的属性一般是遵从 ...
- 社交媒体平台api接口功能_针对社交媒体API的新Java规范请求
社交媒体平台api接口功能 针对Java 7的最新Java规范请求已经浮出水面,提出了一种用于访问私有和公共社交信息网络的API,范围从Facebook和Twitter到企业和机构内的网络. 社交媒体 ...
- 算法API接口文档规范
算法API接口文档规范 参考:百度AI开放平台:https://ai.baidu.com/ai-doc/FACE/yk37c1u4t 接口功能介绍 1.人脸比对:比对两张图片中人脸的相似度,并返回相似 ...
最新文章
- luogu P1843 奶牛晒衣服 | 二分法
- 《算法竞赛进阶指南》打卡-基本算法-AcWing 91. 最短Hamilton路径:位运算、状态压缩dp、dp
- python3数字全排列怎么搞_python3实现字符串的全排列的方法(无重复字符)
- python -使用del语句删除对象引用
- HTML+CSS+JavaScript复习笔记持更(四)——多媒体篇
- matlab用泰勒展开解微分方程,mathematica的解微分方程的能力让人大失所望啊
- python csv文件复制时的编码问题_使用python读取CSV文件时的编码问题
- 好快!京东推出全新快递服务: 最快30分钟送达
- string input must not be null解决办法
- java easyui样式_【Java框架型项目从入门到装逼】第八节 - 用EasyUI绘制主界面
- 国内首款 5G 机型开售;Google Chrome 大部分插件无人用;Firefox 69 Beta 9 发布 | 极客头条...
- 图像的频率谱和功率谱代表什么_功率谱估计:BT ,周期图,Bartlett ,AR ,MVDR,APES,MUSIC...
- 读书印记 - 《批判性思维工具》
- 完成一个个人博客,博客头像可上传本地图片;部分图片实现点击看大图功能
- 什么是面向对象的编程
- 新动态视频壁纸微信小程序源码_支持多种分类短视频-也有静态壁纸
- 耗时一周尝试踩坑,整理了一些Python实用知识点!
- weboffice控件接收html文件,WebOffice 文档控件API
- 低成本16位 250 kSPS 8通道隔离数据采集系统_电工基础电路图讲解
- 算法 64式 7、搜索算法整理_第4部分_46到60题
热门文章
- 【嵌入式Linux】嵌入式项目实战之七步从零编写带GUI的应用之显示系统、输入系统、文字系统
- Linux C语言连接MySQL 增删改查操作
- console_init_r()函数分析
- matlab 输入方程组,弱弱地问,如何输入以下方程组?
- bezier曲线_套娃成神:贝塞尔曲线
- c语言if语句怎么表达字符,C语言if语句的基本用法
- mysql 常用命令集_Mysql 常用命令集
- Spring (Bean, IoC, AOP, SpringMVC)
- 力扣171.Excel表列序号
- 用实例的方式去理解storm的并发度