目录

什么是API

REST简介

RESTful URI的设计

域名

版本

路径

名词vs动词

示例

过滤信息

状态码

返回结果及错误处理

RPC简介

练习

什么是API

API（Application Programming Interface，应用程序编程接口）是一些预先定义的函数或者接口，目的是提供应用

程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无须访问源码，或理解内部工作机制的细节。

要实现一个 API 服务器，首先要考虑两个方面：

• API 风格

  • RPC

  • REST

• 媒体类型

  • JSON

  • XML

  • Protobuf

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

REST简介

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

• REST 中一切实体都被抽象成资源，每个资源有一个唯一的标识 —— URI，所有的行为都应该是在资源上的CRUD 操作

• 使用标准的方法(GET/POST/PUT/DELETE)来更改资源的状态，常见的操作有：资源的增删改查操作

• 无状态：这里的无状态是指每个 RESTful API 请求都包含了所有足够完成本次操作的信息，服务器端无须保持Session --> 无状态对于服务器的弹性扩容是很重要的

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

RESTful URI的设计

域名

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

https://api.example.com

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

https://example.org/api/

版本

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

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

路径

路径又称“终点”，表示API的具体网址，每个网址代表一种资源

名词vs动词

资源作为网址，只能有名词，不能有动词，而且所用的名词往往与数据库的表明对应

对于一个简洁结构，应该始终使用名词

API中的名词应该使用复数，无论子资源或者所有资源

对于资源的具体操作类型，由HTTP动词表示

常用的HTTP动词有四个：

        GET(SELECT)：从服务器取出资源（一项或多项）

        POST(CREATE)：在服务器新建一个资源

        PUT(UPDATE)：在服务器更新资源（客户端提供改变后的完整资源）

        DELETE(DELETE)：从服务器删除资源

还有三个不常用的HTTP动词：

        PATCH(UPDATE)：在服务器更新（更新）资源（客户端提供改变的属性）

        HEAD：获取资源的元数据

        OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的

示例

// 列出所有动物园，返回资源对象的列表（数组）

        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;

过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户，API应该提供参数，过滤返回结果

常见参数：

?limit=10：指定返回记录的数量

?offset=10：指定返回记录的开始位置

?page=2&per_page=100：指定第几页，以及每页的记录数

?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序

?animal_type_id=1：指定筛选条件

状态码

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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

返回结果及错误处理

• 服务器返回的数据格式，应该尽量使用JSON，避免使用XML

• 定制标准化的返回结果

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

• 如果请求出错服务器就应该向用户返回出错信息，一般来说，返回的信息中将error作为键名，出错信息作为键值即可

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

RPC简介

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

通俗来讲，就是服务端实现了一个函数，客户端使用 RPC 框架提供的接口，调用这个函数的实现，并获取返回值。RPC 屏蔽了底层的网络通信细节，使得开发人员无须关注网络编程的细节，而将更多的时间和精力放在业务逻辑本身的实现上，从而提高开发效率。

RPC 的调用过程：

1. Client 通过本地调用，调用 Client Stub

2. Client Stub 将参数打包（也叫 Marshalling）成一个消息，然后发送这个消息

1. Client 所在的 OS 将消息发送给 Server

1. Server 端接收到消息后，将消息传递给 Server Stub

1. Server Stub 将消息解包（也叫 Unmarshalling）得到参数

1. Server Stub 调用服务端的子程序（函数），处理完后，将最终结果按照相反的步骤返回给 Client

   Stub 负责调用参数和返回值的流化（serialization）、参数的打包解包，以及负责网络层的通信。Client 端一般叫 Stub，Server 端一般叫 Skeleton

练习

请你为学生资源设计一组符合RESTful的API

        新增一个学生

        获取id为1的学生信息

        (按条件)获取所有学生信息

                分页展示学生信息，展示第1页，每页10人

                按学生名称升序排列

                展示所有女生信息

        更新学生信息

        删除学生