在一家跨国媒体公司工作的时候, 我是一个团队的一员，负责为客户提供上传服务, print, 并将文件送到指定的邮寄地址. 我们希望客户能够通过我们的应用程序订购产品并跟踪他们的包裹. 初步评估显示，除了交付外，所有工作都可以在内部完成.

而不是自己构建交付功能, 我们决定将其外包，并集成现有交付公司的应用程序编程接口(API)。. REST，或表示状态转移，架构是一个明确的选择. REST APIs 已经成为软件开发的关键部分了吗. 对于核心业务是开发应用程序的团队, 构建外围功能可能非常耗时，并且通常需要在特定领域具有深厚的专业知识. 这就是REST发挥作用的地方. 而不是花费宝贵的资源在内部开发一个功能, 很可能有一个现有的解决方案可以通过REST购买并集成到您的产品中.

86%的开发人员使用REST, REST是目前最流行的 API architecture根据邮差的说法 2023 API状态报告. 调查还显示 46%的组织 计划在未来12个月内增加他们在api上投入的时间和资源.

通过弥合商业和技术世界之间的鸿沟， product managers 处于有利地位 编排API创建. 对REST API原则和最佳实践的基本理解是至关重要的, however, 为了有效地领导团队.

作为一个有软件开发背景的产品经理, 我的方法总是包括亲自动手解决技术问题, 我使用REST在每个角色中都取得了成功. 本指南旨在为产品经理提供帮助团队构建高质量REST api所需的基础知识.

REST API关键原则和最佳实践

REST是一种软件架构风格，它为分布式系统的设计和开发定义了标准, 使他们更容易相互交流. 下面几节将解释REST api的关键特征，以及如何最大限度地发挥它们的潜力.

熟悉数据格式

REST api通常使用JSON (JavaScript对象表示法)或XML(可扩展标记语言)作为数据格式进行通信. 获得对这些格式的基本理解将使您能够解释API响应并设计有效的数据结构. 在我做产品专家的这些年里, 这是我在使用REST api时遇到的唯一数据格式.

XML在具有已建立的基于XML的标准的遗留系统和行业中更为流行, 比如金融或医疗保健, 在这种情况下，维护与现有系统的兼容性更有意义. JSON, 另一方面, 用于各种各样的微服务，由于其轻量级，它已成为大多数现代REST api的主要选择, 人类可读的格式及其与JavaScript的兼容性, 常用的是什么 web development. 它因其简单和高效而广受欢迎. 大多数编程语言都广泛支持JSON，因此它是许多流行api的默认选择, 包括社交媒体平台提供的信息, cloud services, 现代网络应用. 因此，我建议你开始 熟悉JSON first.

掌握基础知识, 创建简单的JSON文件来获得一些实践经验, 用它们做实验, 并学习如何表示数据. 有很多可用的 JSON tools 这可以帮助你验证你的创意.

使用面向资源的设计来强化无状态

REST系统的一个重要特性是它们是无状态的:客户机和服务器作为完全独立的实体存在，为了执行操作不需要知道对方的任何状态. 这分离了客户机和服务器的关注点, 使REST成为连接两个不同组织的理想解决方案.

因为REST api是无状态的, each request is treated in isolation; every request from the client to the server must contain all necessary information for the server to understand and process it. 服务器使用它所拥有的针对给定请求的所有信息进行响应, 如果响应中缺少一些数据, 很可能是请求本身不正确.

由于其无状态特性，REST api使用资源，而不是使用命令作为端点. 把资源看作描述请求所涉及的对象的名词. 使用名词作为端点可以明确每个请求所做的事情.

使用HTTP方法(获取、发布、放置、删除)对这些资源执行操作意味着您可以简化端点名称, 让他们只关注资源. 在交付API的上下文中, for example, 如果要验证地址, 您的端点应该命名 /deliveryAddress (i.e.，资源/名词)而不是 /getAddress (i.e.(动词)，因为您正在使用HTTP方法 GET 检索信息.

资源命名的一致性对于使API具有可预测性和易于使用至关重要. 如果名字不一致, 开发人员很难预测端点的结构, 而且要扩大系统规模也很困难. 一致性可以减少错误，提高集成效率——选择一种命名约定，并在整个API中坚持使用它. 例如，如果你从 customer 对于与用户相关的资源，不要切换到 user 对于一个类似的概念.

为了使集成更加模块化和精确，避免端点过载也很重要. Don’t use a single endpoint for multiple purposes; each resource should have a distinct URL, 和每个HTTP方法(获取、发布、放置、删除)应该对该URL有一个清晰一致的目的. 例如，使用它将是不好的实践 POST / deliveryAddress 检查地址的有效性，并对类似的地址提供建议. 为了避免混淆，应该建立一个单独的端点来提供地址建议，例如: POST / addressSuggestion.

选择一个清晰的路径结构

REST API路径的设计应该帮助服务器知道正在发生什么. 根据最佳实践, 路径的第一部分应该是资源的复数形式, such as /customers，以便输入多个输入参数. 这种格式确保嵌套的资源易于阅读和理解.

在媒体打印组织中，我们使用以下路径结构作为端点: api.mediaprinting.com/customers/321/orders/9.

在这个例子中， 321 是客户ID，是 9 is the order ID. 这条路径的指向很清楚——即使你以前从未见过这条特定的路径, 你和服务器都能理解.

路径应该只包含定位资源所需的信息和特异性. Note that it is not always necessary to add an ID; for example, 向数据库添加新客户时, the POST request to api.mediaprinting.com/customers 不需要额外的标识符，因为服务器将为新对象生成一个ID. 但是，在访问单个资源时，您需要将ID附加到路径上. For example, GET api.mediaprinting.com/customers/ {id} 检索具有指定ID的客户.

参数也可以通过查询字符串传递. In general, 路径参数用于资源标识, 为过滤保留查询参数, sorting, 或者分页结果. 检索客户已完成的订单可以通过以下方式完成: api.mediaprinting.com/customers/321?orderStatus =完成.

学习常用响应代码

来自服务器的响应包含状态码，用于通知客户端操作成功(或失败). 对于每个HTTP方法，都有服务器在成功时应该返回的预期状态码:

GET:返回200 (OK)

POST:返回201(创建)

PUT:返回200 (OK)

DELETE:返回204 (NO CONTENT)

作为产品经理, 您不需要知道每个状态码(有很多), 但是你应该知道最常见的以及它们是如何使用的:

来源:“

熟悉这些状态码将有助于进行故障排除，因为REST api, 和其他技术一样, 会遇到错误. 这些知识将使您能够预测集成和测试过程中的潜在问题 有效沟通 与开发人员一起迅速解决这些问题.

成为一个亲力亲为的产品领导者

理解REST API原则对每个产品经理来说都是至关重要的, 使你能够作为一个领导者做出正确的决定, 与开发人员有效沟通, 提高团队的效率, 并最终优化交付.

REST的简单性和兼容性使其成为创建有效通信的独立微服务的理想架构. 通过选择合适的数据格式, creating clean, 一致的端点, 设计清晰的路径结构, 并根据响应代码采取行动, 您可以利用REST对API的好处.

随着api在网络中变得更加根深蒂固, 实施上面列出的技巧和最佳实践将帮助您构建质量功能，公司将自豪地将其纳入其产品中.