Flask 大型教程，第 23 部分：应用程序编程接口（API）
内容提要
本章讲解为 Microblog 添加 API：以 REST 为设计基础，遵循客户端-服务器、无状态、统一接口等原则；创建 api 蓝图，用 JSON 表示用户资源，实现获取、注册、修改用户等端点；通过令牌认证保护路由，支持令牌的获取与撤销；最后让错误响应支持内容协商。
延伸解读
REST 原则的实用解读
文章详细介绍了 REST 的六个原则，但指出绝大多数公开 API 采用“务实”的 REST 实现，而非严格遵循所有原则。对于开发者而言，这意味着在设计 API 时不必纠结于是否满足所有 REST 约束，而应关注如何让 API 易于使用和扩展。例如，无状态原则要求每个请求包含认证信息，这虽然增加了客户端负担，但换来了服务器易于水平扩展的好处。
用户资源表示的设计考量
在将用户模型转换为 JSON 时，文章特别处理了密码和邮箱字段：密码从不返回，邮箱仅在用户请求自身数据时包含。这体现了 API 设计中的隐私保护意识。同时，通过添加 post_count 等虚拟字段和 _links 超媒体链接，资源表示可以比数据库模型更丰富，方便客户端发现相关资源。这种设计思路可以推广到其他资源。
分页集合的通用实现
文章通过 PaginatedAPIMixin 类实现了集合资源的分页表示，包括 items、_meta 和 _links 部分。这种通用设计避免了为每个资源重复编写分页逻辑，提高了代码复用性。开发者应注意，per_page 参数被限制为最大 100，以防止客户端请求过大页面导致服务器性能问题。这种保护措施在实际 API 中很常见。
错误处理的机器友好性
API 错误响应采用 JSON 格式，包含 error 和可选的 message 字段，并配合 HTTP 状态码。通过注册蓝图级别的错误处理器，所有 API 错误都能统一返回 JSON，而不是 HTML 错误页。这确保了客户端（如移动应用）能够一致地解析错误信息。开发者应确保错误响应包含足够的信息，但避免泄露敏感细节。
Q&A
什么是REST API？它的核心原则有哪些？
REST（表述性状态转移）是Roy Fielding博士提出的一种架构风格，包含六个原则：客户端-服务器、分层系统、缓存、按需代码（可选）、无状态和统一接口。统一接口又包括唯一资源标识符、资源表示、自描述消息和超媒体。
在Flask中如何为应用添加API蓝图？
创建一个新的蓝图目录（如app/api），在__init__.py中创建蓝图对象，然后导入相关模块（如users、errors、tokens）。最后在应用工厂函数中注册蓝图，并设置URL前缀（如/api）。
如何用JSON表示用户资源？
用户资源表示为JSON对象，包含id、username、last_seen、about_me、post_count、follower_count、following_count等字段，以及_links部分包含self、followers、following、avatar等链接。密码和邮箱字段有特殊处理：密码仅用于注册，邮箱仅在用户请求自己数据时返回。
API中如何处理错误响应？
API错误响应采用JSON格式，包含error和message字段。使用HTTP状态码表示错误类别。通过error_response函数生成错误响应，并注册全局错误处理器确保所有错误返回JSON。常见的400错误有专门的bad_request函数。
如何实现用户资源的API端点？
实现GET /api/users/<id>获取单个用户，GET /api/users获取用户集合（支持分页），GET /api/users/<id>/followers和GET /api/users/<id>/following获取关注者列表，POST /api/users注册新用户，PUT /api/users/<id>修改用户信息。使用to_dict和from_dict方法进行序列化和反序列化。
API认证如何实现？
API认证通过令牌（token）实现，客户端在请求中提供令牌以标识用户身份。需要实现获取令牌和撤销令牌的端点，并使用令牌保护API路由。具体实现涉及app/api/tokens.py模块。
