php实现restful风格的json接口,编写 JSON API —— RESTful 风格 API 设计原则与最佳实践...

编写 JSON API —— RESTful 风格 API 设计原则与最佳实践

由 学院君 创建于1年前, 最后更新于 1年前

版本号 #1

9524 views

9 likes

2 collects

概述

在移动互联网时代，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 接口。