常见的 API 设计错误及其避免方法

# Web 开发# 编程# 初学者# API

维护和设计可扩展的 API 是一项艰巨的任务，尤其是当您的项目拥有超过 100 个 API 时。在 API 即服务的时代，了解 API 设计是不可避免的。

在本文中，我们将讨论一些可应用于您的项目的 RESTful API 设计标准，以构建理想的 API 生态系统。

Imagription

关注资源

API 的基本目的是提供对特定资源的访问。API 资源表示 API 提供访问权限的一组数据或功能。

例如，在 CRM（客户关系管理）应用程序中，典型的资源包括：

  • 联系方式
  • 线索
  • 帐户
  • 任务

    • 资源可以是单例（单个帐户）或集合（一组任务）的形式。

    我们可以设计一个格式为“GET /contacts”的 API 来获取所有联系人的列表，或者格式为“PUT /tasks/301”的 API 来更新任务的详细信息。

    正确的 URL 命名

    命名约定对于 URL 来说很重要。RESTful URL 最好使用名词，因为 RESTful API 旨在收集资源和通信，而不是执行动作或操作。

    `获取/联系人`

    `获取/任务/:id`

    `GET /获取联系人`

    `GET /按 id 获取任务/:id`

    使用路径参数

    使用路径参数可以提供一种清晰且结构化的方式来识别 API 内的资源及其关系。

    `获取/任务/:id`

    避免这种情况

    GET /tasks

{
 id:1
}

    维护 API 层次结构

    维护明确定义的资源层次结构有助于定义 API 中不同资源之间的关系。

    对于 CRM 来说

    `获取/用户/{userId}/任务/{taskId}`

    这里API明确根据特定用户下的任务ID来获取任务。

    API 版本控制

    API 会随着产品的发展而修改。因此，对 API 的修改不应影响老用户、老客户端或前端代码。这时版本控制就派上用场了。

    在以下情况下使用 API 版本控制：

  • 重命名或更改任何端点或属性
  • 参数更改
  • 修改数据格式

    • 可以通过使用 URL 路径更改或使用标头来进行版本控制。

    版本在路径本身中定义。

    例如：https://example.com/api/v2/user

    API 标头中定义的版本

    接受：版本=1.0

    维护和设计 API 是一项永无止境的挑战。不同的产品、用例和环境会有所不同。本文涵盖了一些有助于您构建更好的 API 生态系统的方面。

    Imiption

    我和我的团队正在开发 LiveAPI，这是一款超级便捷的 API 文档生成工具。使用 LiveAPI，您可以在几分钟内轻松为任何 Web 项目创建 API 文档。

    此外，一旦您连接，LiveAPI 将根据代码更改使您的 API 文档保持最新。

    尝试 LiveAPI 并分享您的宝贵反馈。保持联系以获取更多技术提示和文章。