Web前端开发技术

Appearance

REST 与 JSON:API ​

元信息 ​

  • 目标：掌握 REST"资源为中心 + 统一动词接口 + 无状态"的 API 设计约定与 JSON:API 响应信封格式，能不看文档猜出规范 REST 接口的用法
  • 关键概念：REST、资源、HTTP 动词、无状态、JSON:API、信封结构
  • 关联阶段：cp3
  • 常见误区：以为 REST 是一种协议或框架（它只是 API 设计风格约定）；以为 URL 里写动词更直观（资源应是名词，操作语义交给 HTTP 动词）；以为 REST 规定了响应体结构（结构是 JSON:API 等补充规范的领域）

REST：API 设计思想的来由 ​

2000 年，Roy Fielding（HTTP 协议的主要设计者之一）在博士论文中提出了 REST（Representational State Transfer，表述性状态转移），用来总结"Web 为什么能扩展到今天这个规模"，并主张把同样的架构原则用在 API 设计上。

REST 的核心主张就几条：

  • 资源为中心：API 的 URL 不再是动词（/getUser、/deleteUser），而是名词化的资源（/users/42）——一切皆资源
  • 统一接口：操作语义全部交给 HTTP 动词表达——GET 读、POST 增、PUT/PATCH 改、DELETE 删（呼应表单的动词语义）
  • 无状态：每个请求自带全部信息，服务器不记"上次聊到哪"（呼应HTTP协议的无状态）
  • 表述：客户端拿到的是资源的表述（通常是 JSON），而不是页面

好处是 API 有了全行业统一的"语法"：看到一个规范的 REST API，不用读文档也能猜出七八成用法。

JSON:API：响应结构的约定 ​

REST 约定了 URL 和动词，但没有约定响应体的结构——字段叫 name 还是 userName？分页信息放哪？错误长什么样？每家 API 一个写法，前端对接一个 API 就要读一遍文档。

JSON:API 规范（2013 年从 Ember.js 社区发起，2015 年发布 1.0）就是为补这一层而生：它规定响应必须长这样——

import "./styles.css";

document.getElementById("app").innerHTML = `
<h1>Hello world</h1>
`;
Open on CodeSandboxOpen Sandbox
  • data：数据本体；type + id 标识资源，具体字段收进 attributes
  • links：相关资源的地址（分页、自身），客户端可以"顺着链接走"
  • 错误也有统一格式（errors 数组），前端可以用一套代码处理所有 API 的错误

来由上它是社区对"REST 之上再统一一层"的努力；代价是信封结构略显啰嗦，因此它是一种约定取舍——学习它的意义不在背格式，而在于体会"接口规范解决的是协作问题"。

实例：同一个资源库的 CRUD ​

用公开测试 API http://restapi.adequateshop.com（一个旅游者资源库）演示统一接口。测试工具：网页版 httpie、浏览器扩展 Yet Another REST Client（下载 crx）、或重型软件 postman。

操作动词 + URL说明
列表（分页）GET /api/Tourist?page=2读集合
单个GET /api/Tourist/26读一个资源
新增POST /api/Tourist + 请求体写
修改PUT /api/Tourist/14842 + 请求体整体替换
删除DELETE /api/Tourist/14842删

新增/修改的请求体（JSON）：

import "./styles.css";

document.getElementById("app").innerHTML = `
<h1>Hello world</h1>
`;
Open on CodeSandboxOpen Sandbox

观察 URL 的规律：集合用复数名词，个体用 id 后缀，操作全靠动词——五条 URL 长得像一家人，这就是 REST 的"统一接口"。对照试试哪些环节是 JSON:API 风格的、哪些只是普通 JSON（提示：它的响应没有 data/attributes 信封——这正是"REST 但非 JSON:API"的例子）。

参考 ​