JSON 与 RESTful API

现代 Web 应用通常采用前后端分离架构。前端页面不再依赖整页刷新完成操作，而是通过 API（应用程序编程接口） 与后端交换结构化的 JSON 数据，从而实现添加、更新、删除等无刷新交互。

认识 JSON 数据格式

JSON（JavaScript Object Notation） 是一种轻量级的纯文本数据交换格式，常用于前后端之间传输数据。它主要由以下几种类型组成：

• 对象（Object）：用花括号 {} 包裹的一组键值对，键名和字符串值必须使用双引号 ""，例如：{"book_id": 1, "name": "乌鸦"}。
• 数组（Array）：用方括号 [] 包裹的有序列表，例如：[1, 2, 3]。
• 布尔值、数字与 null：true、false、123、null 等值不需要加引号。

RESTful API 设计规范与 CRUD

REST 风格的 API 通常把数据抽象为“资源”，并使用标准的 HTTP 方法表示对这些资源的操作。常见的业务操作包括创建、读取、更新和删除，也就是 CRUD。

用 curl 实践 API 调用

下面使用 curl 命令，完整演示对示范书（book_id = 1）的 API 操作流程。

1. 添加书籍到书架（POST + JSON）：

   向书架接口提交一个 JSON 请求体，把书籍编号为 1 的书添加到书架中。

   crow@kali:~$ curl -sS -i -b cookies.txt -H 'Content-Type: application/json' -d '{"book_id":1}' "$target_url/api/bookshelf"
   HTTP/1.1 201 CREATED
   ...
   {"book_id":1,"chapter":1,"chapter_title":"第一章 第十三张床","sync_reference":"READ-1-1","title":"我在医院学斩鬼"}
   

2. 更新阅读进度到第二章（PUT + JSON）：

   使用 PUT 请求更新指定书籍的阅读进度。这里的 chapter 字段必须是整数，而不是字符串。

   crow@kali:~$ curl -sS -b cookies.txt -X PUT -H 'Content-Type: application/json' -d '{"chapter":2}' "$target_url/api/bookshelf/1"
   {"book_id":1,"chapter":2,"chapter_title":"第二章 夜班守则","sync_reference":"READ-1-2","title":"我在医院学斩鬼"}
   

3. 重新查询当前进度（GET）：

   再次请求该书籍的书架记录，确认阅读进度已经更新到第二章。

   crow@kali:~$ curl -sS -b cookies.txt "$target_url/api/bookshelf/1"
   {"book_id":1,"chapter":2,"chapter_title":"第二章 夜班守则","sync_reference":"READ-1-2","title":"我在医院学斩鬼"}
   

常见错误与排错思路

• 如果向 API 提交 JSON 时漏掉了 -H 'Content-Type: application/json'，服务器可能无法识别请求体类型，并返回 415 Unsupported Media Type。
• 如果将数值字段误写成字符串，例如 {"chapter":"2"}，服务器可能返回 400 Bad Request。
• 请求失败时，可以按顺序检查：请求头是否声明了正确内容类型、请求体格式是否合法、字段名称是否正确、字段值类型是否符合接口要求。

除了 GET 和 POST，RESTful 接口还用 PUT、DELETE 等方法表达不同操作。下面用 DELETE 亲手删除一条资源。