Restful风格接口浅析
为什么使用RESTful
1.JSP技术可以让我们在页面中嵌入Java代码,但是这样的技术实际上限制了我们的开发效率,因为需要我们Java工程师将html转换为jsp页面,并写一些脚本代码,或者前端代码。这样会严重限制我们的开发效率,也不能让我们的java工程师专注于业务功能的开发,所以目前越来越多的互联网公司开始实行前后端分离。
2.近年随着移动互联网的发展,各种类型的Client层出不穷,RESTful可以通过一套统一的接口为Web,iOS和Android提供服务。另外对于广大平台来说,比如微博开放平台,微信开放平台等,它们不需要有显式的前端,只需要一套提供服务的接口,RESTful无疑是最好的选择。RESTful架构如下:
五、如何设计Restful风格的API
1.路径设计
—>在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表名对应,一般来说,数据库中的表都是同种记录的”集合”(collection),所以API中的名词也应该使用复数。
—>举例来说,有一个API提供动物园(zoo)的信息,还包括各种动物和雇员的信息,则它的路径应该设计成下面这样。
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees
1 你一直在错误的使用http协议
现在微服务真是火的一塌糊涂!大街小巷,逢人必谈微服务,各路大神纷纷忙着把自家的单体服务拆解成多个Web微小服务!而作为微服务之间通信的桥梁,Web API的设计就显得非常重要。
Http是目前互联网使用最多的协议,没有之一!但是作为Http协议创始人之一的Roy Fielding认为,过去十年,大家都在错误的使用Http协议。删除一个数据,路径往往是 delete/{id} , 更新一条数据,路径往往被定义为update/{id}。你已经被Roy在心里默默的鄙视了!
Roy Fielding提出了一种用于设计Web服务的架构方法,称为Representational State Transfer(REST)。REST的概念是将API结构分离为操作和资源。使用HTTP方法GET、DELETE、POST和PUT操作资源。
设计糟糕的REST API = 浪费时间!
优秀的API就像一位艺术家在舞台上表演,其用户就是观众,能给所有人带来赏心悦目的美感!
2 REST API里面的术语
Resource(资源)是指代表某种东西的对象,它具有一些与之相关的数据,并且可以有一组方法对其进行操作。 例如。 学校,班级和学生是资源,删除,添加,更新是要对这些资源执行的操作。
Collections(集合)是一组资源,例如,211大学是全国211所优质大学的集合。
URL(统一资源定位符)是可以通过其定位资源的路径,并且可以对其执行某些操作。
3 API设计使用名词,而不是动词
例如获取所有学生,可能通过如下api:
/getAllStudents,
增加学生,可能是:/addNewStudent
更新学生,可能是:/updateStudent
删除学生,可能是:/deleteStudent
删除所有学生,可能是:/deleteStudents
获取三好学生,可能是:/getSanHaoStudents
更多操作......等等。
对于不同的操作,会衍生出越来越多的API接口,数量不停的增多,接口将会变得混乱和难以维护。
有没有感觉哪里不对?
URL应仅包含资源(名词)而不包含动作或者动词!增加学生的API路径:/addNewStudent,包含操作addNew以及资源名称Student。
正确的方法是什么?
/schools ,是一个很好的例子,不包含任何动作。但是我们怎么告诉服务器,有关学校资源的操作呢,例如增加,删除或者更新学校?
这就是HTTP方法(GET,POST,DELETE,PUT)(也成为动词)扮角色的地方!API接口的资源应始终为复数,如果我们要访问资源的一个实例,我们可以在URL中传递id或者name之类的。
GET 路径 /schools 获取所有的学校
GET 路径 /schools/清华 获取名字叫清华大学的详细信息
DELETE 路径 /schools/清华 从学校列表中,删除清华大学
资源和资源之间可能有父子关系,那又应该如何设计呢?例如学校的学生,下面是一些示例:
GET /schools/清华/students 获取清华大学的所有学生
GET /schools/清华/students/张三 获取清华大学名字叫张三的学生的详细信息
DELETE /schools/清华/students/张三 删除清华大学名字叫张三的学生
4 合理利用Http本身的方法
HTTP已定义了几组方法,这些方法指示要对资源执行什么类型的操作。我们制定web接口,要合理利用http的方法!
URL是说白了,就是一个句子,其中资源是名词,HTTP方法是动词。
GET 方法从资源请求数据,不应产生任何其他作用。
例如/schools/清华/students,返回所有清华大学的学生
POST方法请求服务器在数据库中创建资源,主要是在提交Web表单时。
/schools/清华/students/张三,在清华大学的学生资源,新增一个张三的学生。
POST是非幂等的,这意味着多个请求将具有不同的效果。
PUT方法请求服务器更新资源或创建资源(如果不存在)。
/schools/清华/students/张三, 对清华大学下的学生资源中,更新或者创建张三。
PUT是幂等的,这意味着多个请求将具有相同的效果。
DELETE方法请求从数据库中删除资源或其实例。
/schools/清华/students/张三,从清华大学的学生集合中,删除学生张三的资源。
5 使用JSON作为通信格式
JSON阅读性更高,扩展性更强,适合各种环境和语言进行解析,现在大的互联网公司,对外提供的API基本都使用JSON。
6 使用HTTP状态码
当客户端通过API向服务器发出请求时,客户端应该知道反馈,无论是失败,成功还是请求错误。 HTTP状态代码是一系列标准化代码,针对http请求的可能会发生的各种情况。 服务器应始终返回正确的状态代码。
很多人喜欢把错误信息放在返回值中,典型的Code和Message,其实比较Low。
下面是Http状态码,可以合理利用处理各种请求反馈,将http自身的错误和服务器内部的错误,有一个很好的区分。
2xx(成功类别)
200 Ok表示GET,PUT或POST成功的标准HTTP响应。
201 Created每当创建新实例时,都应返回此状态代码。 例如,使用POST方法创建新实例时,应始返回201状态代码。
204 No Content表示请求已成功处理,但未返回任何内容。
3xx(重定向类别)
304 Not Modified表示客户端已在其缓存中有响应。 因此无需再次传输相同的数据。
4xx(客户端错误类别)
这些状态代码表示客户端已提出错误请求。
400 Bad Request表示未处理客户端的请求,因为服务器无法理解客户端要求的内容。
401 Unauthorized表示不允许客户端访问资源,并应使用所需凭据重新请求。
403 Forbidden表示请求有效且客户端已通过身份验证,但不允许客户端出于任何原因访问该页面或资源。例如,有时不允许授权客户端访问服务器上的目录。
404 Not Found表示请求的资源现在不可用。
410 Gone表示已移动的请求资源不再可用。
5xx(服务器错误类别)
500内部服务器错误表示请求有效,但服务器完全混淆,并要求服务器提供某些意外情况。
503 Service Unavailable表示服务器已关闭或无法接收和处理请求。大多数情况下,例如服务器正在进行维护。
7 搜索,排序,过滤和分页
所有这些操作都只是对一个数据集的查询。将不会有新的API集来处理这些操作。我们需要使用GET方法API附加查询参数。
下面看几个例子:
GET /schools ? search = 清华大学 在大学集合中,搜索清华大学
GET /schools ? sort = rank_asc 按照升序排列学校
GET /schools ? location = 北京 按照城市对学校过滤
GET /schools ? page=6 获取第六页的学校列表
8 使用版本控制
例如下面两个版本地址:
http://api.yourservice.com/v1/schools/清华
http://api.yourservice.com/v2/schools/清华
在API上加入版本信息可以有效的使用户访问正确的API,v2是新开发功能,开发阶段,让所有用户访问v1,等开发完成统一切到v2。
可以有效的跨版本访问,例如在v2版本,还需要访问v1版本的一些接口
9 总结
1,API接口都用小写
2,使用JSON通信
3,API带版本控制,比如v1,v2
4,使用Token令牌进行鉴权
5,路径中单词连接使用中划线-
6,使用HTTP自身的方法表示增删改查资源, GET:查询,POST:新增,PUT:更新,DELETE:删除
7,合理使用HTTP状态码,200,201,400,401,403,500。比如401表示用户身份认证失败,403表示你验证身份通过了,但是无权限操作资源。
Restful风格接口浅析的更多相关文章
- SpringBoot2.0基础案例(01):环境搭建和RestFul风格接口
一.SpringBoot 框架的特点 1.SpringBoot2.0 特点 1)SpringBoot继承了Spring优秀的基因,上手难度小 2)简化配置,提供各种默认配置来简化项目配置 3)内嵌式容 ...
- 使用SpringBoot编写Restful风格接口
一.简介 Restful是一种对url进行规范的编码风格,通常一个网址对应一个资源,访问形式类似http://xxx.com/xx/{id}/{id}. 举个栗子,当我们在某购物网站上买手机时会 ...
- 『政善治』Postman工具 — 3、补充:restful风格接口的项目说明
目录 (一)RESTful架构风格特点 1.统一接口风格 2.规范的HTTP请求方法 3.HTTP响应码 4.什么是无状态 (二)JSON数据格式说明 1.什么是JSON 2.JSON格式的特点 3. ...
- 第一节:WebApi的纯原生态的RestFul风格接口和路由规则介绍
一. 原生态接口 1. 从默认路由开始分析 在WebApiConfig.cs类中的Register方法中,我们可以看到默认路由如下: 分析:请求地址在 controller 前面需要加上 api/,c ...
- thinkphp5.0极速搭建restful风格接口层实例
作为国内最流行的php框架thinkphp,很快就会发布v5.0正式版了,现在还是rc4版本,但已经很强大了下面是基于ThinkPHP V5.0 RC4框架,以restful风格完成的新闻查询(get ...
- restful风格接口和spring的运用
Restful风格的API是一种软件架构风格,设计风格而不是标准,只是提供了一组设计原则和约束条件.它主要用于客户端和服务器交互类的软件.基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机 ...
- RestFul风格接口示例
REST是英文representational state transfer(表象性状态转变)或者表述性状态转移;Rest是web服务的一种架构风格;使用HTTP,URI,XML,JSON,HTML等 ...
- restful风格接口类型和优点
从事web开发工作有一小段时间,REST风格的接口,这样的词汇总是出现在耳边,然后又没有完全的理解,您是不是有和我相同的疑问呢?那我们一起来一探究竟吧! 就是用URL定位资源,用HTTP描述操作. 知 ...
- 【Spring】构建Springboot项目 实现restful风格接口
项目代码如下: package hello; import org.springframework.boot.SpringApplication; import org.springframework ...
随机推荐
- RabbitMQ生产者消费者模型构建(三)
ConnectionFactory:获取连接(地址,端口号,用户名,密码,虚拟主机等) Connection:一个连接 Channel:数据通信信道,可发送.接收消息 Queue:具体的消息存储队列 ...
- 攻防世界 | level0
先反编译 : int __cdecl main(int argc, const char **argv, const char **envp) { write(1, "Hello, Worl ...
- Sublime Text3 代码编辑器使用笔记
Sublime Text3 作为一款代码的文本编辑器,有许多插件,这一点是我认为 Sublime Text3 很强大的原因之一.插件的安装可以参考下面的文章. Sublime Text3 插件安装教程 ...
- UNITY崩溃的日志
有关UNITY的日志,有两个路径. 1,一般日志路径:C:/Users/xxxx/ AppData/Local/Unity/Editor,此文件夹下有三个文件 ,如下图:Editor.log, Edi ...
- jmeter之登录接口的一次简单压测与分析
前言:登录接口的一次简单压测与分析 1.接口文档 2.配置元件 3.结果分析 1.接口文档 a.拿到接口文档 接口地址:http://localhost:8080/jpress/admin/login ...
- rpm --qf 命令
1. 环境准备: sudo apt-get install rpm (Ubuntu系统) wget ftp://rpmfind.net/linux/fedora-secondary/developme ...
- Logistic Algorithm分类算法的Octave仿真
本次Octave仿真解决的问题是,根据两门入学考试的成绩来决定学生是否被录取,我们学习的训练集是包含100名学生成绩及其录取结果的数据,需要设计算法来学习该数据集,并且对新给出的学生成绩进行录取结果预 ...
- [LeetCode] 72. Edit Distance(最短编辑距离)
传送门 Description Given two words word1 and word2, find the minimum number of steps required to conver ...
- Django first()和last() F查询以及Q查询
一.first()和last() 分别返回queryset的第一项与最后一项,具体用法如下: p = Blog.objects.order_by('title').first() 等同于: try: ...
- 05 - Jmeter连接多台电脑做压力测试
在使用Jmeter进行接口的性能测试时, 由于Jmeter是JAVA应用, 对于CPU的内存消耗比较大, 所以, 当需要模拟数以万计的的并发用户时, 使用单台机器模拟所有用户并发就会有些力不从心了, ...