[ Laravel从入门到精通 ] 编写 JSON API —— RESTful 风格 API 设计原则与最佳实践

概述

在移动互联网时代，Laravel 开发者日常接触最多的任务应该就是编写 JSON API 接口，基于 RESTful 风格或类 RESTful 风格，以便允许第三方应用/客户端应用与后台应用通过这些 API 接口进行交互。

在 Laravel 项目中实现 JSON API 非常简单，框架底层为此做了大量的工作，提供了大量相关的方法、与之相关的资源控制器、以及 API 资源类、API 认证实现等。在「编写 JSON API」这一系列教程中，学院君将围绕如何构建 JSON API 展开，我们将一起学习编写 API 的一些基本原则、Laravel 框架官方提供的用于编写 API 的 工具 、以及一些知名的相关第三方扩展包。

我们首先从编写 JSON API 的基本原则说起。

RESTful 风格 API

REST 是目前最流行的 API 接口设计规范，其全名是 Representational State Transfer，中文译作表现层状态转化，这一规范最早由 HTTP 协议的主要设计者 Roy Thomas Fielding 于 2000 年在他的博士论文中提出，主要目的是便于在不同程序在网络中传递信息。如果一个 API 接口设计符合 REST 规范，我们就将这样的 API 称之为 RESTful 风格 API。

要理解 REST 规范，我们需要把把规范名称拆开来看：

表现层

所谓表现层，指的是 Web 资源的表现层。

在互联网中，每一个 URL 都唯一标识一个独立的 Web 资源，这些资源可能是文本、图片、视频等，而资源的表现层，指的是资源具体呈现的外在表现形式，比如文本可能以 HTML、XML、JSON 等格式呈现，URL 的局限性是只能标识资源的位置，不能标识资源的表现形式，资源的表现形式通常在 HTTP 报文首部通过指定字段来表示，比如我们在请求头中通过 Accept 字段来标识客户端支持的内容类型（表现形式），在响应头中通过 Content-Type 字段来标识返回响应实体的内容类型（表现形式）。

状态转化

当客户端请求服务器上某个 Web 资源（即请求某个 URL）时，有可能会涉及到资源的状态转化，这些状态转化是基于资源的表现层之上的。而要让服务器资源发生状态转化，势必要让客户端使用某种手段对服务器资源进行操作，而在 HTTP 通信中，这些手段就是 HTTP 的请求方法：通过 GET 方法获取资源，通过 POST 方法创建资源，通过 PUT/PATCH 方法更新资源，通过 DELETE 方法删除资源。这些状态转化是基于资源的表现层之上的，通常我们使用的是 JSON 格式数据。

综合上述，RESTful 风格的 API 设计是围绕 Web 资源展开的，在基于 HTTP 协议的 Web 服务中，我们通过 URL 来表示资源的位置，通过在 HTTP 报文首部中设置相应的首部字段来表示资源的类型，资源的位置+类型+实体数据合起来称作资源的表现层，客户端与服务端的交互过程中，对资源的请求和访问可能导致其表现层状态的转化，比如获取、新增、更新、删除等，而这些状态变化则是通过 HTTP 请求方法来实现。

最佳实践

了解了 RESTful 的概念和原则之后，我们来看一下 RESTful 风格 API 的最佳实践：

• 围绕「资源」展开，且这些资源通过 URL 进行标识，比如 /posts 用于表示所有文章， /posts/15 用于表示 ID 为 15 的文章，至于资源名称用单数还是复数，没有统一规定，但通常我们使用复数，另外 URL 要尽可能简单，不要拖泥带水；
• 与资源的交互通过 HTTP 请求方法来实现，而不是将操作动作包含到 URL 中，比如 GET /posts/15 用于获取 ID 为 15 的文章， DELETE /posts/15 用于删除 ID 为 15 的文章；
• 接口的设计需要遵循无状态原则，不同的接口请求之间不要有持久化的 Session 认证，每个接口请求都需要自己独自去认证；
• 返回的响应状态码尽可能精准描述服务器处理结果，比如成功用 2XX 状态码，重定向用 3XX 状态码，资源不存在用 404，没有权限用 403，需要认证用 401，服务器错误用 5XX 状态码，并且对异常情况尽可能在响应实体中予以说明；
• 约定在客户端与服务器交互过程中以 JSON 格式传递数据，即资源的外在表现形式是 JSON。

以前面编写的待办任务项目为例，我们在 Laravel 中通过 Artisan 命令创建资源控制器后，在 routes/api.php 中通过 Route::resource('tasks', 'TaskController'); 注册路由，系统会自动为我们构建遵循 RESTful 风格的 API 接口骨架：

下一篇教程我们将编写对应的控制器方法来实现基于 RESTful 风格的 JSON API 接口。