良好设计的API = 快乐的程序员 ?。
应用程序接口(API)是一种接口,它让应用程序可以轻松地使用另一个应用程序的数据和资源,API 对于一个产品或公司的成功至关重要。
如果没有 API,你大部分喜欢的软件今天就不会存在。例如,Google Maps API 可以让你在 app 或 Web 应用中使用 Google Maps。如果没有它,你将不得不设计和开发自己的地图数据库。这样的话,在地图上显示一个位置需要花费多少时间?
在大多数实际场景中,数据模型 已经存在,但由于我们将讨论 API 设计最佳实践,我将从头开始说起。
以 API 为中心对您的数据进行建模,是设计易于创建、维护和更新 API 的第一步
在设计 API 时,尽量考虑使用通用的术语,而不是使用内部的复杂业务术语,因为这些术语在公司外可能不为人所知。你的 API 可能会对外开放,以允许外部开发人员使用你的 API 开发他们自己的应用。通过使用通用术语,你可以确保使用 API 的开发人员易于了解你的 API,并能快速上手。
假设到你正在建立一个门户网站,让用户点评不同作者的书籍。你的公司可能会使用特定的术语,如创作者、创作、系列等来指代图书作者、书籍和系列。但为了简单起见,并方便外部应用开发者使用你的 API,使用通用的概念而不是公司特定的术语来创建 API 路径。
https://api.domain.com/authors
https://api.domain.com/authors/{id}/books
这有助于新的开发人员快速了解你的 API 是什么,以及如何遍历你的数据模型。
应用程序需要访问你的资源。维护一个资源层次结构可以帮助你更好地构建 API。资源层次结构是指路径中的每个节点,它由一个集合或一个资源组成。
资源可以是一个单一的数据,例如,上面例子中的作者简介。
集合是指一个资源的集合,在我们的例子中,它可以是一个作者所写的书的列表。
合适的资源层次结构可以是:
Base Path -> 作者 (集合) -> profile (资源)
Base Path -> 作者 (集合) -> 书 (集合) -> 书 (资源)
层次结构需要保持一致,以确保开发人员在将其应用程序接入 API 时遇到的问题最少。
为了保持简单性和一致性,这里有一些指导原则可以帮助你:
HTTP 形式的 API 最广泛接受的标准是 REST(Representational State Transfer)。它基本上意味着每个 URL 代表一个对象。
API 目的可以是以下之一:
CRUD!猜对了!
API 通过使用一组 HTTP 命令来处理,这些命令定义了请求的性质和它应该做什么。
GET 从 API 中检索数据。它要求从 API 中获取数据的表示。GET请求可以包含查询参数,以过滤从API接收的结果。
POST 向 API 提交一条记录,该记录将在数据库中创建一个资源。
PUT 一般用于更新服务器上的现有资源。
DELETE 从服务器上删除一个资源。
应用程序和 API 的生命周期越长,应用和 API 对用户的承诺就越大。在某个时间点上,你的 API 将需要修改,因为你无法预见随着需求和业务政策而发生的变化。
因此需要对 API 进行更改。但是 API 可能已经有一个或多个开发者在使用了,所以,重要的是,你所做的更改不会破坏你的合作伙伴开发者的应用。
小版本升级(Minor):当变更不会破坏客户端应用程序的运行时,可以使用小版本升级,例如添加可选字段或支持附加参数。这时候你可以为你的 API 增设小版本。
大版本升级(Major):是那些肯定会破坏现有客户端应用的版本,比如在请求参数中添加一个新的必需参数,或改变返回结果中的字段。
可以通过多种方式来对 API 进行版本控制。
最常见的方法是将版本包含在 URI 中。
https://api.domain.com/v1.0/authors
另外一种方法是使用基于日期的版本控制。URI 中包括将版本发布日期。应用程序开发人员可以很方便了解 API 更改的频率。
另一种方法是在请求标头中包含 API 版本。
https://api.domain.com/authors
x-api-version:v1
最推荐和接受的版本控制方式是,在URI 中使用版本名称。
在数据量越来越大的世界里,不可能在一个屏幕上同时显示所有的数据。所以,让用户在再次请求数据之前,先取到一定数量的结果,这一点很重要。这就是所谓的分页,返回的数据集叫做页面。
建议你在请求和返回结果中使用特定的术语来启用 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 更健壮、简洁并易于与其他应用程序集成。
请记住。
良好设计的API = 快乐的程序员 ?。
英文原文:
https://codeburst.io/best-practices-api-design-61d4697d17ff
下一篇
已是最新文章