开启掘金成长之旅！这是我参与「掘金日新计划 · 2 月更文挑战」的第 9 天，点击查看活动详情

为移动应用编写良好的API

通往最佳用户体验和开发者体验的道路

要理解谁在使用API

知道应用程序将连接到API可能有助于决定协议. API开发者通常以微服务的方式思考问题, 但通常在应用程序中, 功能需要多个微服务来实现任务. 使用BFF(Backend for Frontend)是明智的, 这样复杂的协调工作就在后端完成一次, API就能一次性返回正确的数据, 避免多次来回.

在这之下, BFF将使用多个微型服务, 但鉴于这项工作将在基础设施中完成, 延迟将大大减少, 允许更快的响应时间. 更重要的是, 通过在后端进行这项工作, 我们可以防止移动团队为每个平台(Android、iOS、Web)实施复杂的协调工作. 节省时间和金钱, 提高所有平台的一致性.

有版本

API是不断变化的, 它们就像任何软件一样不断发展, 而且不时地会引入破坏性的变化. 这就是为什么建立一个版本系统是至关重要的. 我在这里说的不是Git, 而是一个适当的版本命名X.y.z. 当合同改变时, 版本也应该改变.

这将防止因为API的改变而破坏应用程序, 此外, 它将促进从一个版本到另一个版本的迁移, 以及测试.

📄 更新文档

文档和协议对于团队之间的良好沟通至关重要, 它们必须保持更新, 最好是使用自动生成文档的技术, 如NodeJS的Swagger-autogen.

这将使移动团队在API不稳定的情况下也能开始实施. API合同中的任何变化都应该导致该API的新版本, 这样任何团队成员都可以很容易地理解需要什么更新.

⚠️ 错误处理

正确地处理错误将防止意外的行为或奇怪的信息传递给终端用户. 错误应该是有意义的, 并被设计成能够被API消费者(即：应用程序)所理解. HTTP错误代码和商业错误代码都应该被使用. 前者将有助于处理一般的处理, 而后者将有助于处理特定的业务场景. 使用业务代码, 应该返回一个纯英文的错误信息. 这将有助于开发人员直接了解什么是错误的. 最后, 错误代码应该被记录下来.

灵活而强大

API应该简单易用, 但足够强大, 通过提供额外的参数来允许复杂的使用情况.

这样一来, 一般的用例就可以很容易地实现, 而不会限制复杂的即将发生的情况. 例如, 你可能有一个默认的每页条目数, 但允许用一个参数覆盖它. 为搜索提供额外的过滤选项, 如日期, 最后X条以及排序选项.

总结

这是一个理想的世界, 在这个世界里, API是以客户为中心建立的, 我相信你可能不得不在这里和那里做出妥协, 但希望这可以成为你的目标状态. 我希望移动和API开发者都能同意这一点, 这样我们就能一起为我们的用户建立美丽的应用程序.

如果你有什么要补充的, 我很想听听你的意见! 什么对你和你的团队最有效?

开启掘金成长之旅！这是我参与「掘金日新计划 · 2 月更文挑战」的第 10 天，点击查看活动详情

为移动应用编写良好的API - 2