![]()
- 前言 -
应用程序接口（API）是一种接口，它让应用程序可以轻松地使用另一个应用程序的数据和资源，API 对于一个产品或公司的成功至关重要。如果没有 API，你大部分喜欢的软件今天就不会存在。例如，Google Maps API 可以让你在 app 或 Web 应用中使用 Google Maps。如果没有它，你将不得不设计和开发自己的地图数据库。这样的话，在地图上显示一个位置需要花费多少时间？![]()
- 为什么要使用 API？ -
- API 是独立于平台的，它们传递数据不受请求平台的影响
在大多数实际场景中，数据模型 已经存在，但由于我们将讨论 API 设计最佳实践，我将从头开始说起。
![]()
- 数据建模与结构化 -
以 API 为中心对您的数据进行建模，是设计易于创建、维护和更新 API 的第一步在设计 API 时，尽量考虑使用通用的术语，而不是使用内部的复杂业务术语，因为这些术语在公司外可能不为人所知。你的 API 可能会对外开放，以允许外部开发人员使用你的 API 开发他们自己的应用。通过使用通用术语，你可以确保使用 API 的开发人员易于了解你的 API，并能快速上手。假设到你正在建立一个门户网站，让用户点评不同作者的书籍。你的公司可能会使用特定的术语，如创作者、创作、系列等来指代图书作者、书籍和系列。但为了简单起见，并方便外部应用开发者使用你的 API，使用通用的概念而不是公司特定的术语来创建 API 路径。https://api.domain.com/authors https://api.domain.com/authors/{id}/books
这有助于新的开发人员快速了解你的 API 是什么，以及如何遍历你的数据模型。![]()
- 编写面向资源的 API -
应用程序需要访问你的资源。维护一个资源层次结构可以帮助你更好地构建 API。资源层次结构是指路径中的每个节点，它由一个集合或一个资源组成。资源可以是一个单一的数据，例如，上面例子中的作者简介。集合是指一个资源的集合，在我们的例子中，它可以是一个作者所写的书的列表。Base Path -> 作者 (集合) -> profile (资源)Base Path -> 作者 (集合) -> 书 (集合) -> 书 (资源)
层次结构需要保持一致，以确保开发人员在将其应用程序接入 API 时遇到的问题最少。
为了保持简单性和一致性，这里有一些指导原则可以帮助你：- 命名集合和资源时使用美式英语（例如：color 而不是 colour）
- 使用更简单、更常用的词来保持清晰，例如 delete 而不是 remove
- 如果你使用的资源与其他 API 使用的资源相同，请使用相同的术语以保持一致。
- 对集合使用复数形式（例如：authors、books 等）。
![]()
- RESTful 接口 -
HTTP 形式的 API 最广泛接受的标准是 REST(Representational State Transfer)。它基本上意味着每个 URL 代表一个对象。
API 通过使用一组 HTTP 命令来处理，这些命令定义了请求的性质和它应该做什么。GET 从 API 中检索数据。它要求从 API 中获取数据的表示。GET请求可以包含查询参数，以过滤从API接收的结果。POST 向 API 提交一条记录，该记录将在数据库中创建一个资源。![]()
- API 版本控制 -
应用程序和 API 的生命周期越长，应用和 API 对用户的承诺就越大。在某个时间点上，你的 API 将需要修改，因为你无法预见随着需求和业务政策而发生的变化。因此需要对 API 进行更改。但是 API 可能已经有一个或多个开发者在使用了，所以，重要的是，你所做的更改不会破坏你的合作伙伴开发者的应用。![]()
- 了解主要和次要更新 -
小版本升级（Minor）：当变更不会破坏客户端应用程序的运行时，可以使用小版本升级，例如添加可选字段或支持附加参数。这时候你可以为你的 API 增设小版本。大版本升级（Major）：是那些肯定会破坏现有客户端应用的版本，比如在请求参数中添加一个新的必需参数，或改变返回结果中的字段。https://api.domain.com/v1.0/authors
另外一种方法是使用基于日期的版本控制。URI 中包括将版本发布日期。应用程序开发人员可以很方便了解 API 更改的频率。
https://api.domain.com/2020-06-15/authors
https://api.domain.com/authors x-api-version：v1
最推荐和接受的版本控制方式是，在URI 中使用版本名称。
![]()
- 分页 -
在数据量越来越大的世界里，不可能在一个屏幕上同时显示所有的数据。所以，让用户在再次请求数据之前，先取到一定数量的结果，这一点很重要。这就是所谓的分页，返回的数据集叫做页面。建议你在请求和返回结果中使用特定的术语来启用 API 中的分页功能。这些术语有- STRING page_token（在请求中发送）
- STRING next_page_token（由 API 返回）
page_token 请求 API 需要返回哪个页面。这通常是一个字符串。对于第一次API调用，page_token = "1"page_size 定义了返回结果中应该返回多少条记录。例如page_size = 100，在API调用中最多返回100条记录。next_page_token 定义了翻页的下一个 token。如果在page_token = "1" 之后有额外的数据，返回的值是应当是 next_page_token="2"如果没有更多的数据可用，而且用户已经到达数据的终点，则返回一个空白值 next_page_token="" 。这些就是设计 API 的最佳实践。它让你的 API 更健壮、简洁并易于与其他应用程序集成。
作者：Varun Joshi
来源：
https://codeburst.io/best-practices-api-design-61d4697d17ff
美团技术：到店结算平台实践（胶片）
美团技术：到店供应链及商品平台建设实践（胶片）
美团技术：CRM平台建设实践（胶片）
美团技术：交易平台建设实践（胶片）
推送有营养的技术干货文章；
总覆盖会员100000+人；资深架构、总监等职位以上3000+人。
定期在线分享超过100期，线下技术沙龙超过70次、覆盖20多个等城市！
关注技术架构、研发管理、互联网金融、电商、大数据、区块链、人工智能等方向！
加入中生代技术群聊，投稿等请添加白明微信：zsdwyq，注明姓名、职称和技术方向，通过后加入中生代技术群，和群友们共同学习成长！