在说restful风格的API之前,我们要先了解什么是rest。什么是restful。最后才是restful风格的API!

PS(REST:是一组架构约束条件和原则,REST是Roy Thomes Fielding在他2000年的博士论文中提出的。Roy Thomas Fielding是HTTP协议(v1.0和v1.1)的主要设计者、Apache服务器作者之一、Apache基金会第一任主席。)

什么是REST?

REST不是”rest”这个单词,而是几个单词的缩写 REpresentation State Transfer,直接翻译:表现层状态转移,这个翻译不太好理解。网上找到一个比较通俗的说法是:URL定位资源,用HTTP动词(GET,POST,DELETE,PUSH等)描述操作 。REST最大的几个特点为:资源、统一接口、URI和无状态。

什么是Restful?

Restful基于REST构建的API就是Restful风格。

为什么使用Restful?

(1). 有的团队之前一直使用JSP作为表现层,但是这样的技术限制了他们的开发效率,他们需要将前端组给出静态html页面转换为jsp页面,并且写一些js代码,甚至是一些前端代码。这样会严重限制他们的开发效率,也不能让后端组专注于业务功能的开发,所以目前越来越多的互联网公司开始实行前后端分离。

(2). 近年随着移动互联网的发展,各种类型的客户端层出不穷,Restful可以通过一套统一的接口为PC、微信(H5)、IOS和Android提供服务,这样的接口不需要前端样式,只提供数据。

Restful 是目前最流行的 API 设计规范,用于 Web 数据接口的设计。

下面才开始进入正题,如何设计Restful风格的API。

如何设计Restful风格的API

RestfulAPI就是由后台(SERVER端)来提供接口,前端来调用。前端调用API向后台发起HTTP请求,后台响应请求将处理结果反馈给前端。也就是说Restful 是典型的基于HTTP的协议。那么RESTful API有哪些特征呢?

(1).Resource资源,首先是弄清楚资源的概念。资源就是网络上的一个实体、一段文本、一张图片或者一首歌曲。资源总是要通过一种载体来反应它的内容。文本可以用TXT,也可以用HTML或者XML、图片可以用JPG格式或者PNG格式,JSON是现在最常用的资源表现形式。

(2).统一接口。Restful风格的数据元操作CRUD(create,read,update,delete)分别对应HTTP方法:GET用来获取资源,POST用来新建资源(也可以用于更新资源),PUT用来更新资源,DELETE用来删除资源,这样就统一了数据操作的接口。

(3).HTTP状态码,在REST中都有特定的意义:200,201,202,204,400,401,403,500。比如401表示用户身份认证失败,403表示你验证身份通过了,但这个资源你不能操作。

(4). 无状态。所谓无状态即所有的资源都可以URI定位,而且这个定位与其他资源无关,也不会因为其他资源的变化而变化。

Restful 是典型的基于HTTP的协议,HTTP连接最显著的特点是客户端发送的每次请求都需要服务器回送响应,在请求结束后,会主动释放连接。从建立连接到关闭连接的过程称为“一次连接”。前面一次请求与后面一次请求没有必然的联系,所以是无状态的。

下面介绍如何设计出易于理解和使用的 API。

一、URL 设计

1.1 动词 + 宾语

RESTful 的核心思想就是,客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如,GET /articles这个命令,GET是动词,/articles是宾语。

1.2 动词的覆盖

有些客户端只能使用GETPOST这两种方法。服务器必须接受POST模拟其他三个方法(PUTPATCHDELETE)。

这时,客户端发出的 HTTP 请求,要加上X-HTTP-Method-Override属性,告诉服务器应该使用哪一个动词,覆盖POST方法。

1.3 宾语必须是名词

宾语就是 API 的 URL,是 HTTP 动词作用的对象。它应该是名词,不能是动词。比如,/articles这个 URL 就是正确的,而下面的 URL 不是名词,所以都是错误的。

1.4 复数 URL

既然 URL 是名词,那么应该使用复数,还是单数?这没有统一的规定,但是常见的操作是读取一个集合,比如GET /articles(读取所有文章),这里明显应该是复数。

为了统一起见,建议都使用复数 URL,比如GET /articles/2要好于GET /article/2

1.5 避免多级 URL

常见的情况是,资源需要多级分类,因此很容易写出多级的 URL,比如获取某个作者的某一类文章。除了第一级,其他级别都用查询字符串表达。

二、状态码

2.1 状态码必须精确

客户端的每一次请求,服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。HTTP 状态码就是一个三位数,分成五个类别。这五大类总共包含100多种状态码,覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的(或者约定的)解释,客户端只需查看状态码,就可以判断出发生了什么情况,所以服务器应该返回尽可能精确的状态码。API 不需要1xx状态码,下面介绍其他四类状态码的精确含义。

2.2 2xx 状态码

200状态码表示操作成功,但是不同的方法可以返回更精确的状态码。

POST返回201状态码,表示生成了新的资源;DELETE返回204状态码,表示资源已经不存在。

此外,202 Accepted状态码表示服务器已经收到请求,但还未进行处理,会在未来再处理,通常用于异步操作。

2.3 3xx 状态码

API 用不到301状态码(永久重定向)和302状态码(暂时重定向,307也是这个含义),因为它们可以由应用级别返回,浏览器会直接跳转,API 级别可以不考虑这两种情况。

API 用到的3xx状态码,主要是303 See Other,表示参考另一个 URL。它与302307的含义一样,也是"暂时重定向",区别在于302307用于GET请求,而303用于POSTPUTDELETE请求。收到303以后,浏览器不会自动跳转,而会让用户自己决定下一步怎么办。

2.4 4xx 状态码

4xx状态码表示客户端错误,主要有下面几种。

400 Bad Request:服务器不理解客户端的请求,未做任何处理。

401 Unauthorized:用户未提供身份验证凭据,或者没有通过身份验证。

403 Forbidden:用户通过了身份验证,但是不具有访问资源所需的权限。

404 Not Found:所请求的资源不存在,或不可用。

2.5 5xx 状态码

5xx状态码表示服务端错误。一般来说,API 不会向用户透露服务器的详细信息,所以只要两个状态码就够了。

500 Internal Server Error:客户端请求有效,服务器处理时发生了意外。

503 Service Unavailable:服务器无法处理请求,一般用于网站维护状态。

三、服务器回应

3.1 不要返回纯本文

API 返回的数据格式,不应该是纯文本,而应该是一个 JSON 对象,因为这样才能返回标准的结构化数据。所以,服务器回应的 HTTP 头的Content-Type属性要设为application/json。客户端请求时,也要明确告诉服务器,可以接受 JSON 格式,即请求的 HTTP 头的ACCEPT属性也要设成application/json

3.2 发生错误时,不要返回 200 状态码

有一种不恰当的做法是,即使发生错误,也返回200状态码,把错误信息放在数据体里面,这张做法实际上取消了状态码,这是完全不可取的。正确的做法是,状态码反映发生的错误,具体的错误信息放在数据体里面返回。

3.3 提供链接

API 的使用者未必知道,URL 是怎么设计的。一个解决方法就是,在回应中,给出相关链接,便于下一步操作。这样的话,用户只要记住一个 URL,就可以发现其他的 URL。这种方法叫做 HATEOAS。

上面就是一些关于restful风格的API的说明了,希望对你有帮助!

走前别忘了加个关注呦......

restful风格的API的更多相关文章

  1. PHP实现RESTful风格的API实例(三)

    接前一篇PHP实现RESTful风格的API实例(二) .htaccess :重写URL,使URL以 /restful/class/1 形式访问文件 Options +FollowSymlinks R ...

  2. PHP实现RESTful风格的API实例(二)

    接前一篇PHP实现RESTful风格的API实例(一) Response.php :包含一个Request类,即输出类.根据接收到的Content-Type,将Request类返回的数组拼接成对应的格 ...

  3. PHP实现RESTful风格的API实例(一)

    最近看了一些关于RESTful的资料,自己动手也写了一个RESTful实例,以下是源码 目录详情: restful/ Request.php 数据操作类 Response.php 输出类 index. ...

  4. PHP实现Restful风格的API

    Restful是一种设计风格而不是标准,比如一个接口原本是这样的: http://www1.qixoo.com/user/view/id/1表示获取id为1的用户信息,如果使用Restful风格,可以 ...

  5. [01] 浅谈RESTful风格的API

    1.什么是RESTful风格的API REST,即Representational State Transfer,可以理解为"(资源的)表现层状态转化". 在网络上,我们通过浏览器 ...

  6. Gin实战:Gin+Mysql简单的Restful风格的API(二)

    上一篇介绍了Gin+Mysql简单的Restful风格的API,但代码放在一个文件中,还不属于restful风格,接下来将进行进一步的封装. 目录结构 ☁ gin_restful2 tree . ├─ ...

  7. Gin实战:Gin+Mysql简单的Restful风格的API

    我们已经了解了Golang的Gin框架.对于Webservice服务,restful风格几乎一统天下.Gin也天然的支持restful.下面就使用gin写一个简单的服务,麻雀虽小,五脏俱全.我们先以一 ...

  8. springMvc中restful风格的api路径中把小数点当参数,SpringMvc中url有小数点

    在springMvc web项目中restful风格的api路径中有小数点会被过滤后台拿不到最后一个小数点的问题, 有两种解决方案: 1:在api路径中加入:.+ @RequestMapping(&q ...

  9. Dubbo 03 Restful风格的API

    目录 Dubbo03 restful风格的API 根路径 协议 版本 用HTTP协议里的动词来实现资源的增删改查 用例 swagger(丝袜哥) OpenAPI 资源 编写API文档 整合Spring ...

随机推荐

  1. hash模块 hashlib 和hmac

    hashlib模块 用于加密相关的操作,代替md5模块和sha模块,主要提供SHA1,SHA224,SSHA256,SHA384,SHA512,MD5算法 直接看代码案例: ---------md5- ...

  2. IOS学习目录

    一.UI 1.基础控件 2.高级控件 二.多线程网络 1.网络请求.网络安全 2.

  3. 转载:开发者眼中最好的 22 款 GUI 测试工具

    对于很多同学来说gui程序的测试是一个难点,所以我从网上转载了一篇关于gui测试的一篇文章,里面罗列的很多工具,大家可以尝试一下学习学习. 英文原文:22 best GUI testing tools ...

  4. boot/bootsect.S

    !! SYS_SIZE is the number of clicks (16 bytes) to be loaded.! 0x7F00 is 0x7F000 bytes = 508kB, more ...

  5. MfC基础--绘图基础--win32

    1.vc使用的控件分为三类: windows标准控件--MFC对这些进行了再封装 ActiveX 控件 其他MFC控件类 2.CWind是所有窗口的基类 3.GDI也属于一种API,主要用于绘图,(G ...

  6. 黑马程序员—创建JDBC框架及原理分析

    对于Java数据库的连接,由最初学习的每次全部手工代码,到后面的不断利用知识简化代码量:这是不断学习的过程,就像人类由原始社会的钻木取火到当代的文明,都是一步步过来的! 本文不从最开始的JDBC入门开 ...

  7. MyEclipse优化全攻略

    (0) 吐槽 Eclipse仅仅是个半成品有木有?什么都须要自己安装插件,新手非常难用有木有? 安装上插件以后了版本号兼容和各种问题烦死人有木有? 都怪碎片和版本号乱公布有木有? IntelliJ I ...

  8. Posix消息队列实现机制

    本文是对<Unix 网络编程 卷2:进程通信>的笔记. 引言 消息队列是进程间通信的一种方式,可是如果不理解他的实现原理,会有众多不理解之处,下面就结合本书中的例子,对posix消息队列来 ...

  9. redis中键的生存时间(expire)

    1.redis中可以使用expire命令设置一个键的生存时间,到时间后redis会自动删除它 expire 设置生存时间(单位/秒) pexpire 设置生存时间(单位/毫秒) ttl/pttl 查看 ...

  10. HTML之表单

    目录 表单的结构 get方式与post方式 输入 单行文本输入框 提交按钮和重置按钮 密码输入框 复选框 单选按钮 图像按钮 文本选择输入框 隐藏框 多行文本输入框 下拉列表框 新增输入元素 新增其他 ...