文摘  RESTful API的初步理解和设计规范

一、什么是RESTful API？

要弄清楚什么是RESTful API,首先要弄清楚什么是REST。

REST 即 REpresentational State Transfer 。英语的直译就是“表现层状态转移”。

Resource：资源，即数据。

Representational：某种表现形式，比如用JSON，XML，JPEG等；

State Transfer：状态变化。通过HTTP动词实现。

REST是一种软件架构风格。主要有以下特点：

1.资源通过URL来指定和操作。

2.对资源的操作包括获取、创建、修改和删除，正好对应HTTP协议的GET、POST、PUT 和 DELETE 方法。

3.连接是无状态性的。

4.能够利用Cache机制来提高性能。

它基于HTTP协议，并不涉及新的技术，而且与SOAP,XML-RPC相比，更加简洁、高效。

下面解释一下什么是RESTful: URL定位资源，用HTTP动词（GET,POST,PUT,DELETE)描述操作。

所以RESTful API就是REST风格的API。RESTful API 是一套互联网应用程序的 API 设计理论。

首先，我们来看几组例子。

传统的 URL :

restful风格的 URL ：

可以看出RESTFul API的特点：

·  基于“资源”，数据也好、服务也好，在RESTFul设计里一切都是资源。

·  无状态。一次调用一般就会返回结果，不存在类似于“打开连接-访问数据-关闭连接”这种依赖于上一次调用的情况。

·  URL中通常不出现动词，只有名词

·  URL语义清晰、明确

·  使用HTTP的GET、POST、DELETE、PUT来表示对于资源的增删改查

·  使用JSON不使用XML

例：

网站：/get_user?id=3

RESTFul: GET /user/3 (GET是HTTP类型)

有些同学可能会说，GET、POST我也经常用啊。但是在网站里的GET和POST同RESTFul中的GET、POST是不一样的。网站里使用GET、POST的选择点在于，简单的用GET、复杂对象用POST；但在REST里，GET对应的是查询一个资源，而POST对应的是新增一个资源，意义是决然不同的。理解这一点非常重要。

说了这么多，到底RESTful长什么样子的呢？

GET: http://www.xxx.com/source/id 获取指定ID的某一类资源。例如： GET:http://www.xxx.com/friends/123表示获取ID为123的会员的好友列表。如果不加id就表示获取所有会员的好友列表。

POST: http://www.xxx.com/friends/123表示为指定ID为123的会员新增好友。

其他的操作类似就不举例了。

那么在什么场景下使用RESTful API呢？

在当今的互联网应用的前端展示媒介很丰富。有手机、有平板电脑还有PC以及其他的展示媒介。那么这些前端接收到的用户请求统一由一个后台来处理并返回给不同的前端肯定是最科学和最经济的方式，RESTful API就是一套协议来规范多种形式的前端和同一个后台的交互方式。

RESTful API由后台也就是SERVER来提供前端来调用。前端调用API向后台发起HTTP请求，后台响应请求将处理结果反馈给前端。也就是说RESTful 是典型的基于HTTP的协议。

总结

符合REST设计标准的API，即RESTful API。REST架构设计，遵循的各项标准和准则，就是HTTP协议的表现，换句话说，HTTP协议就是属于REST架构的设计模式。比如，无状态，请求-响应。。。

二、RESTful API的设计原则和规范

那么RESTful API有哪些设计原则和规范呢？

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

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

3，URI。可以用一个URI（统一资源定位符）指向资源，即每个URI都对应一个特定的资源。要获取这个资源访问它的URI就可以，因此URI就成了每一个资源的地址或识别符。一般的，每个资源至少有一个URI与之对应，最典型的URI就是URL。

4，无状态。所谓无状态即所有的资源都可以URI定位，而且这个定位与其他资源无关，也不会因为其他资源的变化而变化。有状态和无状态的区别，举个例子说明一下，例如要查询员工工资的步骤为第一步：登录系统。第二步：进入查询工资的页面。第三步：搜索该员工。第四步：点击姓名查看工资。这样的操作流程就是有状态的，查询工资的每一个步骤都依赖于前一个步骤，只要前置操作不成功，后续操作就无法执行。如果输入一个URL就可以得到指定员工的工资，则这种情况就是无状态的，因为获取工资不依赖于其他资源或状态，且这种情况下，员工工资是一个资源，由一个URL与之对应可以通过HTTP中的GET方法得到资源，这就是典型的RESTful风格。

接着来看一看RESTFul API的一些最佳实践原则：

·  使用HTTP动词表示增删改查资源， GET：查询，POST：新增，PUT：更新，DELETE：删除

·  返回结果必须使用JSON

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

· 如果出现错误，返回一个错误码。比如我通常是这么定义的：

1.API必须有版本的概念，v1，v2，v3

2.使用Token令牌来做用户身份的校验与权限分级，而不是Cookie。

3.url中大小写不敏感，不要出现大写字母

4.使用 - 而不是使用 _ 做URL路径中字符串连接。

5.有一份漂亮的文档~（很重要）

以上只是列出了RESTFul的部分实践原则，并非全部。 给出一个典型的RESTFul API设计风格：

https://api.z.cn/v1/product/recent?page=3&size=20

以上URL非常容易理解，分页获取最新若干的Product资源。

RESTful API还有其他一些规范。

1：应该将API的版本号放入URL。GET:http://www.xxx.com/v1/friend/123。或者将版本号放在HTTP头信息中。我个人觉得要不要版本号取决于自己开发团队的习惯和业务的需要，不是强制的。

2：URL中只能有名词而不能有动词，操作的表达是使用HTTP的动词GET,POST,PUT,DELETEL。URL只标识资源的地址，既然是资源那就是名词了。

3：如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。?limit=10：指定返回记录的数量、?page=2&per_page=100：指定第几页，以及每页的记录数。

最后，我们想聊一下，RESTFul API到底好用吗？

某些情况好用，某些情况非常不好用。什么情况好用，什么情况不好用呢？

我的一个经验性的总结：对于开放的API，豆瓣、新浪微博、GitHub，好用，非常合适；对于内部开发，不好用。

基于资源型的RESTFul API 接口粒度和返回结果过于的“粗”，它通常返回的都是完整的数据模型，这对于客户端非常不友好。但开放API之所以开放，就是因为它不知道你到底需要什么返回结果，既然不知道，那么我干脆都返回给你。这样的好处是通用，但客户端不好处理。你只需要一个字段，服务器啪的丢给你十几个，作为客户端开发者你怎么想？

内部开发由于需求非常明确，通常来说服务器是不应该简单粗暴的直接甩资源实体给客户端的。那RESTFul API就不能接入到内部开发吗？当然不是，我们需要灵活一些借鉴RESTFul中的优点，来设计我们的内部API。那么如何简化，这就不是一篇文章能够说清楚的了，也没有一个统一的标准，需要自己去琢磨和体会。

最后举个例子吧，我个人在开发内部接口时会保留绝大多数的REST 特性，但我不会严格的只写增、删、改、查四个接口。必要的时候，还是要灵活处理一下。而且错误码、状态码这些非常优秀的特性，必须保留。

好了，关于RESTFul我们就介绍到这里。特别强调，接口设计是一个非常依赖于经验和重构的技术活儿，设计接口需要有一些艺术家的天赋（真实体会），你看GitHub的接口就非常的“美”。不要觉得很简单，真的比写代码还难。难道大家不觉得，有时候起名字真的是一件很难的事儿嘛？

参考网址：

https://www.simcf.cc/4113.html 

https://blog.csdn.net/u013063153/article/details/72811976

转载请注明： ITTXX.CN--分享互联网 » RESTful API的初步理解和设计规范

最后更新：2019-01-11 19:01:45