什么是 REST API？

无抓取抓取 API 暴露了应用程序请求结构化网络数据所使用的文档化 HTTP 操作。

REST API 是围绕表现层状态转移（Representational State Transfer）设计的接口，一种网络系统的架构风格。REST 描述了交互的限制，而不是一个 URL 拼写或数据格式。资源具有标识符，客户端交换表示，统一接口使组件在不知道每个特定应用程序过程的情况下理解消息。

许多服务被称为 REST API，因为它们使用 HTTP 和 JSON。这些成分本身并不是定义。一个有用的问题是接口如何使用资源身份、标准方法语义、无状态交互、缓存信息以及应用状态之间的链接。查看这些选择有助于团队在不争论标签的情况下评估现有 API。

资源和表示

资源是可以被识别的概念事物，例如产品、报告或集合。表示是传递描述其当前状态的消息形式。服务器的内部数据库对象不一定直接暴露。Roy Fielding 的 REST 架构章节 解释资源和表示如何适应统一接口。

客户端可能请求一个报告资源并接收包含其状态和链接的 JSON。另一个客户端可能接收不同的表示，如果 API 支持的话。资源身份保持稳定，而表示可以随时间变化。这个区别有助于解释为什么 API 应该记录标识符和媒体类型的含义，而不是假设每个 JSON 对象就是资源本身。

集合资源也需要明确的语义。一份报告列表可能暴露过滤和分页，但服务器应该定义排序和页面令牌的含义。一个恰好返回数组的 URL 并不是自我解释的。客户端需要足够的合同细节，以便在不静默重复或跳过记录的情况下穿过集合。

统一接口和 HTTP 方法

REST 强调统一接口：组件通过通用消息语义进行交互，而不是为每个对象单独定制命令语言。HTTP 提供 GET、POST、PUT、PATCH 和 DELETE 等方法，但选择的方法应与实际操作匹配。 HTTP 语义标准 定义方法的含义和相关响应属性。

GET 旨在检索表示，而不请求状态更改作为操作的目的。一个只读端点如果秘密收费一个订单或删除记录，会违反客户端期望，即使其 URL 看起来整洁。POST 支持根据资源的语义进行处理；PUT 表达目标资源表示的替换。正确的选择取决于实际合同，而不是抄袭到设计文档中的助记表。

方法语义也影响中介、缓存和客户端工具。缓存可以以不同于写操作的方式思考 GET 响应。一个将每个操作放在 POST 后面的 API 可能有效，但放弃了一些共享词汇。相反，强迫将操作放入 GET 中以显得 RESTful 可能会导致更严重的语义问题。

无状态交互和应用状态

在 REST 中，每个请求都携带服务器理解其所需的信息，而不依赖于来自先前请求的会话状态。无状态并不意味着服务器无法存储产品记录或帐户数据。它意味着相对于客户端当前的应用状态，交互是自包含的。Fielding 的分析将该特性与可见性和可扩展性联系在一起。

认证仍然可以存在。客户端可以在每个请求中发送凭据，而服务器维护用户数据库。一个光标或任务标识符也可以识别早先创建的资源，只要新请求使其上下文明确。边界很重要：服务器要求客户端发出“第二步”的同时记住“第一步”所指的哪个未命名操作，会造成隐藏的会话耦合。

无状态请求更容易单独检查，但它们可能携带重复的元数据。这是权衡，而不是声称每个请求都是廉价的理由。保护凭据并避免在通过日志传播的 URL 中存储敏感值。资源标识符可以指向服务器数据，而客户端仍然发送所有信息以满足预期操作。

可缓存性和响应含义

REST 包括缓存约束，因为可重用响应可以减少网络工作。服务器应沟通在何种条件下表示可以被重用。 HTTP 缓存指南 解释新鲜度和验证机制。返回 JSON 的 API 在数据和授权模型允许的情况下仍然可以受益于缓存控制。

公共目录响应和私人账户余额需要不同的缓存策略。如果响应依赖于授权或请求头，缓存设计必须反映这种依赖关系。不正确的重用可能泄漏信息或将过期数据呈现为当前数据。因此，可缓存性是产品和安全决策，而不是对每个 GET 的通用指令。

状态代码应描述请求结果。对于每个失败，200 和错误对象的组合可能使通用客户端和可观察性变得不那么有用。单独的状态也是不够的：响应正文必须在需要的地方说明特定于应用程序的细节。共同设计这两个层次，然后记录客户端在空集合、缺失资源或已接受的异步任务时应该做什么。

REST、RPC和任务导向数据API

RPC风格的API通过共享端点或操作字段暴露命名操作。REST导向的API通过统一接口暴露资源状态。两者都可以是合法的设计。其区别在于交互语义而非质量。将操作端点称为REST并不使其资源导向，而将其称为RPC也不使其不适合定义的任务。

该 Scrapeless Scraping API介绍 描述了用于结构化数据的演员选择操作。其请求使用演员选择任务。该具体接口应由其记录的HTTP合同描述；它不必被强制贴上教科书REST标签。客户端代码应遵循实际操作、输入和结果形状。

基于任务的操作可以返回任务标识符以便后续结果检索。客户端应知道它是在查看提交确认还是完成的数据。资源导向设计可能将该任务建模为资源，但关键的实际点是生命周期的清晰性。该 Scraper API演员指南 说明了为什么演员家族和结果封装必须单独解释。

如何审查REST API合同

选择一个代表性的工作流程并绘制其接触的资源。识别每个资源的URL、允许的方法、表示字段以及预期失败情况下的状态代码。然后问自己请求是否可以独立理解。这个练习比统计有多少个URL路径包含名词更有用。

检查链接和状态转换。如果响应提供下页游标或任务结果URL，客户端可以遵循记录的路径，而不是构建未记录的路线。如果API要求客户端了解隐藏的排序规则，请记录或重新设计该依赖关系。当客户端可以使用消息语义而不是逆向工程服务器内部时，统一接口约束获得实际价值。

最后，通过授权环境中真实的响应验证接口。架构示例可以描述预期的行为，但只有返回的状态、头部集和正文显示部署服务的实际操作。对于 Scrapeless Scraping API，从产品的当前文档和狭窄的演员工作流程开始。不要根据REST的普遍概念推断不支持的字段或端点。

结论

REST API对资源交互应用架构约束：明确的身份、表示、统一接口、无状态请求和有意义的缓存行为。HTTP和JSON是实现这些思想的常见工具，但单独任何一个都不能证明符合性。通过可观察的合同和它支持的工作流程来判断API。