RESTful API设计

今天听到一个陌生的名词“RESTful API”，后来在网上求解了一下，发现原来是请求接口的意思。

对于前端开发人员，很多时候需要与后端的数据进行对接，而这个对接的数据请求的接口，便是本文的主题。

什么是RESTful API？

简单来说，RESTful API 是基于HTTP协议产生的一种相对简单的API设计方案，属于无状态传输。RESTful 的核心是 everything is a “resource”，所有的HTTP action，都应该是相应resource上可以被操作和处理的，而API就是对资源的管理操作，而这个具体操作是由 HTTP action 指定的。

（这里就可以把API看做是服务器与客户端之间进行连接的一个接口，客户端可以从API这个入口获取、修改服务器里面的资源）

HTTP协议语义使用方法

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。
HEAD : 从服务器获取报头信息（不是资源）

一些例子

GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

WEB服务接收与返回的互联网资源类型

客户端与服务端进行交互响应时，需要规定双方能够接受何种类型的媒体表现形式，最常见的以application开头的媒体格式类型有：

application/json： JSON数据格式

application/xhtml+xml：XHTML格式

application/xml： XML数据格式

application/atom+xml：Atom XML聚合格式

API设计原则

1、URL

URL中应尽量使用名词，尽量避免使用动词；

应该尽量将API部署在专用域名之下；

https://api.example.com

如果确定 API 很简单，不会有进一步扩展，可以考虑放在主域名下；

https://example.org/api/

应该将API 的版本号放入URL，或者将版本号放在HTTP头信息中；

https://api.example.com/v1/

2、路径

路径又称”终点”（endpoint），表示API的具体网址。

在RESTful架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的”集合”（collection），所以API中的名词也应该使用复数。

举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

https://api.example.com/v1/zoos

https://api.example.com/v1/animals

https://api.example.com/v1/employees

3、找到特定领域的媒体类型，根据特定的领域来设计媒体类型

在《RESTful Web APIs》一书中提及到当你想要发布一个API的时候，首先要做的就是找到一个已有的特定领域特定设计。重复造轮子是没有意义的。

在数据返回格式方面，大部分的网站优先提供Xml、JSON的数据返回，Google定义的GData就是在Atom基础上作了扩展，还有一些网站提供了php的数据返回。

4、其他

易拓展性：一个易拓展的API设计方案，可以让你延缓实现功能，因为“如果需要的话，后面再添加也很方便”。不需要的功能就不添加；

灵活性：API应该具有足够的灵活性来支持上层UI；

可移植性：这个API可以运行在任何操作系统上；

API应该对程序员友好，并且在浏览器地址栏容易输入；

文章参考地址:https://sanwen8.cn/p/2ddcbVD.html