RESTful API介绍

1. 什么是 API

• API（Application Programming Interface，应用程序编程接口）是一些预先定义的函数或者接口，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无须访问源码，或理解内部工作机制的细节。

• 要实现一个 API 服务器，首先要考虑两个方面：API 风格和媒体类型。

• Go 语言中常用的 API 风格是 RPC 和 REST，常用的媒体类型是 JSON、XML 和 Protobuf。

• 在 Go API 开发中常用的组合是 gRPC + Protobuf 和 REST + JSON。

2. REST 简介

REST 代表表现层状态转移（REpresentational State Transfer），由 Roy Fielding 在他的 论文 中提出。REST 是一种软件架构风格，不是技术框架，REST 有一系列规范，满足这些规范的 API 均可称为 RESTful API。REST 规范中有如下几个核心：

HTTP 方法 行为 URI 示例

1. REST 中一切实体都被抽象成资源，每个资源有一个唯一的标识 —— URI，所有的行为都应该是在资源上的CRUD 操作
2. 使用标准的方法(GET/POST/PUT/DELETE)来更改资源的状态，常见的操作有：资源的增删改查操作
3. 无状态：这里的无状态是指每个 RESTful API 请求都包含了所有足够完成本次操作的信息，服务器端无须保持Session

无状态对于服务端的弹性扩容是很重要的。

REST 风格虽然适用于很多传输协议，但在实际开发中，REST 由于天生和 HTTP 协议相辅相成，因此 HTTP 协议已经成了实现 RESTful API 事实上的标准。在 HTTP 协议中通过 POST、DELETE、PUT、GET 方法来对应 REST 资源的增、删、改、查操作，具体的对应关系如下：

HTTP 方法	行为	URI	示例说明
GET	获取资源列表	/users	获取账号列表
GET	获取一个具体的资源	/users/admin	获取 admin 账号的详细信息
POST	创建一个新的资源	/users	创建一个新账号
PUT	以整体的方式更新一个资源	/users/1	更新 id 为 1 的账号
DELETE	删除服务器上的一个资源	/users/1	删除 id 为 1 的账号

3.RESTful RUI的设计

1. 域名

​ 应该尽量将API部署在专用域名之下。如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

​ 2. 版本（Versioning）

方法一：应该将API的版本号放入URL。

方法二：将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种做法。

https://api.example.com

https://example.org/api/

http://www.example.com/app/1.0/foo
http://www.example.com/app/1.1/foo
http://www.example.com/app/2.0/foo

因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URL。版本号可以在HTTP请求头信

息的Accept字段中进行区分（参见Versioning REST Services）：

​ 3. 路径（Endpoint）

路径又称"终点"（endpoint），表示API的具体网址，每个网址代表一种资源（resource）

举例来说，获取产品的API可以这样定义

# 列出所有动物园，返回资源对象的列表（数组）
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：

过滤信息

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件
参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoos/ID/animals 与 GET /animals?
zoo_id=ID 的含义是相同的。

常见的参数状态码（Status Codes）

200 OK - [GET]：服务器成功返回用户请求的数据
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与 401 错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

返回结果及错误处理（Error handling）

1. 服务器返回的数据格式，应该尽量使用JSON，避免使用XML
2. 定制标准化的返回结果

{
"code": 10002,
"message": "Error occurred while binding the request body to the struct."
"data":{}
}

{
"code": 10002,
"error": "Error occurred while binding the request body to the struct."
}

4. RPC 简介

• 根据维基百科的定义：远程过程调用（Remote Procedure Call，RPC）是一个计算机通信协议。该协议允许运行于一台计算机的程序调用另一台计算机的子程序，而程序员无须额外地为这个交互作用编程。

• 通俗来讲，就是服务端实现了一个函数，客户端使用 RPC 框架提供的接口，调用这个函数的实现，并获取返回值。

• RPC 屏蔽了底层的网络通信细节，使得开发人员无须关注网络编程的细节，而将更多的时间和精力放在业务逻辑本身的实现上，从而提高开发效率。

RPC 的调用过程如下（图片来自 How RPC Works)：

1. Client 通过本地调用，调用 Client Stub
2. Client Stub 将参数打包（也叫 Marshalling）成一个消息，然后发送这个消息
3. Client 所在的 OS 将消息发送给 Server
4. Server 端接收到消息后，将消息传递给 Server Stub
5. Server Stub 将消息解包（也叫 Unmarshalling）得到参数
6. Server Stub 调用服务端的子程序（函数），处理完后，将最终结果按照相反的步骤返回给 Client
Stub 负责调用参数和返回值的流化（serialization）、参数的打包解包，以及负责网络层的通信。Client 端一
般叫 Stub，Server 端一般叫 Skeleton。