【RESTful】RESTful API 接口设计规范 | 示例

概念

本质：一种软件架构风格
核心：面向资源设计的API

解决问题：

• 降低开发的复杂性
• 提高系统的可伸缩性

例如：设计一套API，为多个终端服务。

设计概念和准则

• 网络上的所有事物都可以被抽象为资源
• 每一个资源都有唯一的资源标识，对资源的操作不会改变这些标识
• 所有的操作都是无状态的（本次操作、下次操作、上次操作之间无关系）

资源：网络上的一个实体、具体信息。

HTTP

RESTful 与HTTP协议操作无关，但是它是按照HTTP的思想进行设计的，所以有必要知道HTTP

参考官方文档：https://tools.ietf.org/html/rfc2616

schema://host[:port]/path[?query-string][#author]

• shceme 指定低层使用的协议（如http,https,ftp）
• host 服务器的IP地址或域名
• port 服务器端口，默认为80
• path 访问资源的路径
• query-string 发送给http服务器的数据，常用于对资源进行筛选操作
• anchor 锚，链接

请求

• 格式：请求行、消息报头、请求正文

请求行格式： Method Request-URI HTTP-Version CRLF

如： GET/HTTP.1.1 CRLF

• 请求方法

GET ： 请求获取Request-URI 所标识的资源
POST ：在Request-URI 所标识的资源后附加新的数据
HEAD ： 请求获取由Request-URI所标识的资源的响应消息报头

PUT ： 请求服务器存储一个资源，并用Request-URI作为其标识
DELETE ：请求服务器删除Request-URI所标识的资源
OPTIONS ： 请求查询服务器性能，或者查询与资源相关的选项和需求

对资源的操作：创建、编辑、请求、删除

响应

• 格式：状态行、消息报头、响应正文

状态行格式：HTTP-Version Status-Code Reason-Phrase CRLF

如： HTTP/1.1 200 OK

• 常用响应状态码（在RESTful 中有重要应用）

200 OK //客户端请求成功

400 Bad Request //客户端请求有语法错误，不能被服务器所理解

401 Unanthorized //服务器收到请求，但是服务器拒绝提供服务

404 Not Found //请求资源不存在

500 Internal Serval Error //服务器发生不可预期的错误

503 Server Unavailable // 服务器当前不能处理客户端的请求

RESTful 架构与其他架构的区别

API 的开发方式不止一种，另一种比较流行的开发方式是SOAP WebService。

SOAP WebService

WebService 是一种跨编程语言和跨操作系统平台的远程调用技术。其通过HTTP协议发送请求和接收结果时采用XML格式封装，并增加了一些特定的HTTP消息头，这些特定的HTTP消息头和XML内容格式就是SOAP协议。

对比

• 效率与易用性：SOAP由于各种需求不断扩充其本身协议的内容，导致在SOAP处理方面的性能有所下降。同时在易用性方面以及学习成本上也有所增加。而RESTful API 在请求方法、资源、地址都进行了规范，其最大限度的利用了HTTP最初的应用协议的设计理念。
• 安全性：RESTful 对于资源型服务器接口比较适合，适合对于效率要求很高，但是对于安全要求不高的场景。SOAP 的成熟性可以给需要提供给多开发语言的，对于安全性的要求较高的接口设计带来便利，你可以在客户端和服务端应用证书进行安全措施。所以关键看应用场景。

使用RESTful

设计RESTful API

• 资源路径（URI）：RESTful的核心是面向资源，如何规划资源路径很重要

• HTTP动词(请求方式)：如get,post,delete,put

• 过滤信息：例如获取资源列表时有分页操作/查询操作，这时要合理分配过滤信息，过滤信息设置太多，有可能会违反RESTful API 关于URI方面的限定。

• 状态码：当客户端发送一个请求时，服务端应当响应什么状态码

• 错误处理：如当发现客户端传入的参数有问题时，该返回什么样的状态信息。

• 返回结果：如POST资源的时候，需要返回一个资源实例；GET资源列表时，需要返回一个资源数组；

资源路径

在RESTful架构中，每个网址代表一个资源，所以网址中不能有动词，只能有名词。一般而言，API中的名词应该使用复数。例如，使用users反映用户资源的URI，而不是使用user。

例如：有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，那么它的资源路径应设计成如下样子。

https://api.example.com/v1/zoos  //动物园资源。使用https协议头;加入v1版本号，因为以后可能会更改api。版本号的加入有两种做法，一种是加入到地址中，另一种是加入到HTTP请求头中;zoos复数

https://api.example.com/v1/animals //动物资源

https://api.example.com/v1/employees //雇员资源

HTTP动词

对资源的操作有创建、读取、更新、删除(CURD)，由HTTP动词表示。

• GET ： 从服务器去除资源
• POST ：在服务器新建一个资源
• PUT：在服务器更新资源（客户端提供改变后的完整资源，服务端返回完整的更新字段）
• PATCH：在服务器更新资源（客户端提供改变的属性，服务端返回只发生了更新的字段）
• DELETE：从服务器删除资源

例如：

POST/zoos : 新建一个动物园
GET/zoos/ID : 获取某个指定动物园的信息
PUT/zoos/ID : 更新某个指定动物园的信息
DELETE/zoos/ID : 删除某个动物园

过滤信息

如果记录数量过多，服务器不可能都将它们返回给用户。这时就需要进行筛选。筛选时，API应该提供一个参数，过滤一下返回的结果。

例如：

?offset = 10 :指定返回记录的开始位置
?page = 2&per_page = 100 :指定第几页，以及每页的记录数
?sortby = name&order = asc :指定返回结果排序，以及排序顺序
?animal_type_id = 1 :指定筛选条件

状态码

服务器向用户返回的状态码和提示信息，使用标准的HTTP状态码

• 200 OK 服务器成功返回用户请求的数据
• 201 CREATED 新建或修改数据成功
• 204 NO CONTENT 删除数据成功
• 400 BAD REQUEST 用户发出的请求有错误
• 401 Unauthorized 表示用户没有认证，无法进行当前操作
• 403 Forbidden 表示用户的访问是被禁止的
• 422 Unprocesable Entity 当创建一个对象时，发生一个验证错误。例如创建用户资源时需要用户名、密码，而前端只提供用户名字段，那么就要返回一个422 状态码，并返回错误信息：”密码不能为空“
• 500 INTERNAL SERVER ERROR 服务器内部错误，此时服务端无法处理任何请求。

错误处理

如果状态码是4xx或5xx,就应该向用户返回出错信息。一般而言，返回的信息中将error作为键名，出错信息作为键值即可，例如：

{
  "error":"参数错误"
}

返回结果

针对不同操作（如GET,POST），服务器向用户返回的结果应该符合以下规范：

• GET/collections: 返回资源对象的列表（数组）
• GET/collections/identity : 读取资源时，传入标识符(identity),服务端返回标识符指定的单个资源对象
• POST/collections : 返回新生成的资源对象
• PUT/collections/identity : 返回完整的资源对象
• PATCH/collections/identity : 返回被修改的属性
• DELETE/collections/identity : 返回一个204状态码和空响应体

DHC Client 用于测试API

• 安装DHC 谷歌浏览器插件：

名为： 基于REST的Web服务客户端
先下载： http://chromecj.com/web-development/2015-03/401.html

或在谷歌商店 ：https://chrome.google.com/webstore/detail/rest-web-service-client/ecjfcmddigpdlehfhdnnnhfgihkmejin?hl=zh-CN

然后安装。

本地开发环境搭建

• 安装PHP环境集成包 XAMPP 或 upupw

• 添加虚拟主机，以及取消跨站目录限制 httpd-vhosts.conf文件中 找到添加的域名，将php_admin_value xxx这句开头加入井号进行注释
  

• 添加虚拟主机的本地hosts解析 ： 更改本地hosts文件，添加 127.0.0.1 api.com本地域名解析
  

确认设计要素

项目需求

• 用户登录、注册
• 文章发表、编辑、管理、列表

确认设计要素

• 资源路径： /users , /articles
• HTTP动词： GET,POST,DELETE,PUT
• 过滤信息： 文章分页筛选
• 状态码： 200，404，422，403…
• 错误处理：输出JSON格式错误信息
• 返回结果：输出JSON数组或JSON对象

数据库设计

在数据库中新建2张表：

• 用户表： ID、用户名、密码、注册时间
• 文章表： 文章ID、标题、内容、发表时间、用户ID

添加.htaccess Apache重写文件

之后就可以在IDE中进行相应的开发编码工作。

当然，处理RESTful API设计思想，还有最近流行的GraphQL，它是一种API查询语言，其将所见即所得的思想引入，能帮助提升开发的体验与应用的性能。（参考：http://graphql.cn/ ）

参考

• 慕课教程
• Restful API 的设计规范
• 理解RESTful架构
• RESTful架构基础