在一家跨国媒体公司工作的时候, 我是一个团队的一员，负责为客户提供上传服务, print, 并将文件送到指定的邮寄地址. We wanted customers to be able to order products and track their packages all through our application. 初步评估显示，除了交付外，所有工作都可以在内部完成.

而不是自己构建交付功能, we decided to outsource it and integrate an existing delivery company’s application programming interface (API). REST，或表示状态转移，架构是一个明确的选择. REST APIs 已经成为软件开发的关键部分了吗. 对于核心业务是开发应用程序的团队, building peripheral features can be time-consuming and often demands deep expertise in a niche domain. 这就是REST发挥作用的地方. 而不是花费宝贵的资源在内部开发一个功能, there is likely an existing solution that can be bought and integrated into your product using REST.

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

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

作为一个有软件开发背景的产品经理, 我的方法总是包括亲自动手解决技术问题, 我使用REST在每个角色中都取得了成功. This guide aims to empower product managers with the foundational knowledge they need to help teams build quality REST APIs.

REST API关键原则和最佳实践

REST is a software architectural style that defines standards for the design and development of distributed systems, 使他们更容易相互交流. The following sections explain the key characteristics of REST APIs and how you can maximize their potential.

熟悉数据格式

REST APIs often communicate using JSON (JavaScript Object Notation) or XML (Extensible Markup Language) as data formats. Gaining a basic understanding of these formats will enable you to interpret API responses and design effective data structures. 在我做产品专家的这些年里, 这是我在使用REST api时遇到的唯一数据格式.

XML is more prevalent in legacy systems and industries with established XML-based standards, 比如金融或医疗保健, 在这种情况下，维护与现有系统的兼容性更有意义. JSON, 另一方面, is used for a wide variety of microservices and has become the dominant choice for most modern REST APIs due to its lightweight, 人类可读的格式及其与JavaScript的兼容性, 常用的是什么 web development. 它因其简单和高效而广受欢迎. Most programming languages extensively support JSON and it is thus the default choice for many popular APIs, 包括社交媒体平台提供的信息, cloud services, 现代网络应用. 因此，我建议你开始 熟悉JSON first.

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

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

An important feature of REST systems is that they are stateless: The client and server exist as entirely separate entities and do not need to know anything about the other’s state in order to perform an action. 这分离了客户机和服务器的关注点, 使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. 服务器使用它所拥有的针对给定请求的所有信息进行响应, 如果响应中缺少一些数据, 很可能是请求本身不正确.

Due to their stateless nature, rather than using commands as endpoints, REST APIs use resources. 把资源看作描述请求所涉及的对象的名词. 使用名词作为端点可以明确每个请求所做的事情.

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

Consistency in resource naming is crucial to making an API predictable and easy to use. 如果名字不一致, 开发人员很难预测端点的结构, 而且要扩大系统规模也很困难. Consistency leads to fewer errors and more efficient integration—pick a naming convention and stick with it throughout the API. 例如，如果你从 customer 对于与用户相关的资源，不要切换到 user 对于一个类似的概念.

To make integration more modular and precise, it is also important to avoid overloading endpoints. Don’t use a single endpoint for multiple purposes; each resource should have a distinct URL, 和每个HTTP方法(获取、发布、放置、删除)应该对该URL有一个清晰一致的目的. 例如，使用它将是不好的实践 POST / deliveryAddress for both checking the validity of the address and for providing suggestions on similar addresses. To avoid confusion, a separate endpoint for providing address suggestions should be built, say, POST / addressSuggestion.

选择一个清晰的路径结构

REST API paths should be designed in a way that helps the server know what is happening. 根据最佳实践, 路径的第一部分应该是资源的复数形式, such as /customers，以便输入多个输入参数. 这种格式确保嵌套的资源易于阅读和理解.

In the media-printing organization, we used the following path structure for our endpoints: api.mediaprinting.com/customers/321/orders/9.

In this example, 321 是客户ID，是 9 is the order ID. It is clear what this path points to—even if you’ve never seen this specific path before, 你和服务器都能理解.

The path should contain only the information and specificity needed to locate the resource. Note that it is not always necessary to add an ID; for example, 向数据库添加新客户时, the POST request to api.mediaprinting.com/customers would not need an extra identifier, as the server will generate an ID for the new object. 但是，在访问单个资源时，您需要将ID附加到路径上. For example, GET api.mediaprinting.com/customers/ {id} 检索具有指定ID的客户.

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

学习常用响应代码

Responses from the server contain status codes to inform the client of the success (or failure) of an operation. For each HTTP method, there are expected status codes a server should return upon success:

GET:返回200 (OK)

POST:返回201(创建)

PUT:返回200 (OK)

DELETE:返回204(无内容)

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

来源:“

Familiarity with these status codes will be helpful when troubleshooting because REST APIs, 和其他技术一样, 会遇到错误. 这些知识将使您能够预测集成和测试过程中的潜在问题 有效沟通 与开发人员一起迅速解决这些问题.

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

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

REST’s simplicity and compatibility make it an ideal architecture for creating independent microservices that 有效沟通. 通过选择合适的数据格式, creating clean, 一致的端点, 设计清晰的路径结构, 并根据响应代码采取行动, 您可以利用REST对API的好处.

随着api在网络中变得更加根深蒂固, implementing the tips and best practices outlined above will assist you in building quality functions that companies will proudly incorporate into their products.