design\project\学习 API Design 读书笔记

API 设计

一、API 设计基础

原文链接 Designing Quality APIs

明确 API 设计目标是什么？

当人们在技术选择上存在分歧时，往往是因为他们在目标上不一致

• 如何确定你的目标？抓重点

• 你的工作中遇到的最关键的问题是什么？如果不能抓住关键问题，那就不算出色的工作。为了找到解决方案，你必须时刻盯着关键问题

API 设计的基础定义（交互过程）

• 分为客户端和服务端

• 客户端通过调用服务的的 action 获得数据

• 交互必须快速、简单、安全

整个互联网都是建立在 URI 的基础之上的

API 的复杂性

• 软件通常在遇到变更（change）时，难于修改

  • 软件本身功能点多，功能复杂性

  • 软件建立在一定的假设的前提上，这些前提很容易变更，包括：

    • 从业务视角来看，我们的业务需求持续变更

      • 存在老系统变更

      • 业务需求变更

      • 业务场景变更

    • 从技术实现视角来看，我们总是追求更好的解决方案

      • 选用的数据库变更

      • 选用的实现技术

      • 选用的程序语言变更

• 软件集成（integrate）复杂问题，集成通常是多维度的、海量的

  • 有些系统，缺失基础的 API 造成集成复杂

  • 每个系统有自己独立的 API ，为了集成，你需要全部学习这些 API，（n 的平方 - n） 造成集成复杂

关键 API

• 尽管很复杂，区分一些解决关键问题的： 关键 API

• 其他 API 只负责模块间的通信

主要的 API 设计风格（style）

• 实体 CRUD 接口 （Entity-oriented），又叫 Rest 风格接口

  • 使用代码操纵另一个模块暴露的实体（通过操作实体，改变行为）

  • 栗如：

    {
        type: "/log",
        ...
    }
    POST       /logs
    GET        /logs/1
    DELETE     /logs/1
    ...
    

• 功能（behavier）接口（Procedure-oriented）

  • 使用代码调用另一个模块的功能接口（通过行为，修改实体）

  • 栗如：

    // 通常会有很多接口配合使用
    /getAllLogs/getAllSuccessLogs/verrifyd
    /verifyLogLocation/locationNeeded
    /locationNeeded/createLocation
    /createLocation/getPlatform
    ...
    

• Rest 风格接口便于统一管理，避免每个系统有自己的 API 风格，降低学习成本

  • 但不要和你的后端数据模型一致，每个 Entity 包含多个 Table 数据模型

  • 只是使用统一的 API 定义风格

关键 API ，API 属性选取

• 全应用统一的 API 设计风格

• 统一的传输模型（分布式系统通信）

• 自由的扩展（free to implementation assumptions）

统一的 API 设计风格

• RestAPI 的矛盾

  • restAPI 希望：摒弃 HTTP 之上的 web 层概念，用 HTTP 解决一切。

  • 但是RestAPI 没有必需的，查询或版本（version）的处理

• 如何设计统一风格的 API

  • 定义通用的，有实际意义的 URL，就和定义表名一样。栗如：/customers,/accounts,/orders

  • 定义通用的，有实际意义的资源 schema

  • 定义其他复杂接口时，不得扰乱这些基础的定义

• 示栗：

  {
      // 常见错误：该接口缺乏应用程序标识 `logs`
      id: "12345",
      type: "/log",
      ...
  }
  
  {
      // 为 ID 提供应用程序标识
      id: "/logs/12345",
      type: "/log",
      ownerID: "98765"
      ...
  }
  {
      id: "/logs/12345",
      type: "/log",
      // 错误：如果 ownerID 不是 person 而是机构？
      ownerID: "98765"
      ...
  }
  {
      id: "/logs/12345",
      type: "/log",
      // 指定 identity 为一个 URI
      owner: "rpc的url/98765"
      ...
  }
  {
      id: "/logs/12345",
      type: "/log",
      // 不合适，identity 指定为，可能会修改的 name
      owner: "rpc的url/name"
      ...
  }
  

应用集成的最基本问题是：存储在不同的应用程序中的实体之间的转换

一个最主要的原因是：缺乏应用程序标识，数据 identity，12345 依赖于 log 应为 log.12345，ownerID 依赖于 URI

• 如何设计 query API

  https://domain.com/person/Joe/pets/Lassie
  

  改进为：（query API 多次调用会得到不同的结果）

  https://domain.com/search?type=/dog&name=Lassie&owner=(name=Joe)
  

• 当设计非 关键 API 时：重点考虑：效率高，易于解析，与编程语言匹配

• 当设计 关键 API 时：应考虑独立于现有技术和使用模式，考虑其适应变化能力

• 统一的 API 设计其他原则

  • 不要传递包含不同的类型数据的集合，这样不便于解析。栗如：List