Google AIPs 小记

Read the latest article and comment on Notion.

API Improvement Proposals

• API 的大致分类

  • Standard methods: GET / List / Create / Update / Delete
  • Standard methods 和其他methods 的 batch operations
  • Standard methods 和其他methods 的 long-running operations
  • Jobs 接口
  • Import and export 数据接口
  • item method / collection method / db method / stateless method

  特殊接口

  • Revision 接口，一个资源的历史记录，之所以叫’revision’，是为了和API 的‘version’ 区分开

    • get，记得在返回的name 里加上revision id。

    • tag，给一个revision 加上human readable 的标签，之后revision id 和tag 都能用来get revision。

      💡 If the user calls the Tag method with an existing tag, the request must succeed and the tag updated to point to the new requested revision ID. This allows users to write code against specific tags (e.g. published) and the revision can change in the background with no code change.

    • list

    • commit，基于最新版本的resource 创建revision，可以在一些条件下自动创建，也可以开放出来把时机判断交给用户。

    • rollback，把某个revision 设置成线上最新的数据。

      💡 Note: When rolling back, the API should return a new revision of the resource with a new revision ID, rather than reusing the original ID. This avoids problems with representing the same revision being active for multiple ranges of time.

    • delete。可以导致线上resource 变化，但是不能导致resource 被删除，当被删除的revision 是最后一个revision 时，应拒绝请求。

    • child revision。适当考虑一个资源下的某个子资源也有revision 的需求。

  • Purge 接口，当需要删除的数据量级超过Batch Delete 语义，考虑使用Purge
    • 支持使用 filter 来筛选出更多的资源，但是因为数量过大没必要返回。
    • 只有当 request 的 force == true 时才执行删除。
    • response 要返回 purge_count
    • 当request force == false 时，返回purge_count 和约100个 purge_sample

• AIPs 体现出的设计原则

  **方便外界调用方的使用。**一些原则对内部API 要求过高了。

  • 统一规范：doc 详细cover 了很多细节。
    • 比如每个resource response 的第一个field 都得是 canonical name，无论request。
      • 对于collections response，则是 parent ，不是 name 。
    • 分页只返回 page_token 不返回 offset
      • token 可以代表更多信息。
      • 防止用户解析分页的内部逻辑，给接口更新带来灵活性。
      • token 一般3天后过期
    • order_by 字段也用string ，保证灵活性。
    • update 只能用 PATCH ， PUT 有可能会破坏兼容性。
      • PUT 代表全替换，有时候客户端觉得一个对象的fields 是旧的 $F$，但可能服务端已经是新的 F ′ F^{'}