restful风格的API

最新推荐文章于 2024-11-12 11:19:19 发布

dongjiekui1757

最新推荐文章于 2024-11-12 11:19:19 发布

阅读量165

点赞数

文章标签：前端 json 后端 ViewUI

原文链接：http://www.cnblogs.com/wzfwaf/p/10524860.html

版权

在说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 动词的覆盖

有些客户端只能使用GET和POST这两种方法。服务器必须接受POST模拟其他三个方法（PUT、PATCH、DELETE）。

这时，客户端发出的 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。它与302和307的含义一样，也是"暂时重定向"，区别在于302和307用于GET请求，而303用于POST、PUT和DELETE请求。收到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。