一种新的 OpenAPI 设计思想(草稿)

Open API V3 接口设计规范草案

问题

在 v2 版本的接口中,我们发现接口最大的问题是:使用方容易用错,而究其根源,主要在于接口的说明文档,实现逻辑,测试用例,使用方理解等之间存在一致性问题,具体来说,在于以下几点:

  1. 接口设计越来越严重依赖某一个具体的产品需求,而不是基于普遍需求的抽象,导致越来越多的后期调整。接口设计及调整缺乏一致性保证,从而使得理解及使用成本上升,用错的概率增大
  2. 单个接口的功能及返回会随着时间的推移而发生变化,而这种变化信息无法及时的传递给以及在使用的调用方。比如增加传入参数,比如做一些性能优化,还有微调某些字段的含义(如曾经不返回正确的关注粉丝数,后来改为返回正确的数了)
  3. 测试人员对需求的理解与开发人员不一致,偶尔不全面,导致功能点漏测,自动化测试覆盖不足
  4. 使用方依赖的接口定义文档,SDK都出现与实现不一致,严重过时现象。文档与代码无法保持完全一致
  5. 使用方阅读文档描述文字,容易出现遗漏某些说明,从而因信息缺失导致不当甚至错误的使用

解决思路

因为 API 的设计,实现,使用都是程序员,或 IT 相关人士,在这个群体中,最通用的,且不容易发生理解错误的,不是自然语言,而是代码(为了避免编程语言的选择不同,这里我们使用类似 C 语言的“伪代码”模式进行描述),所以在 v3 版本中,主要的解决思路是,将 API 接口相关的所有信息,都以伪代码的形式进行描述,描述信息本身也以 API 的形式进行组织和公开,给所有相关方提供同等的,详细的,具体的信息,包括设计,实现,测试和使用方。

  1. 以一种程序可识别和处理的 DSL schema 方式定义 API,且 API schema 定义是公开的,类似 wsdl 文件。
  2. API schema 中包括以下约束信息:参数,返回字段,状态码(错误码),SLA保证,当前状态等
  3. 提供一套根据 API schema 进行 API 实现的规则说明,工具和最佳实践例子
  4. 提供一套根据 API schema 进行自动化测试的规则说明,工具和例子
  5. 提供一套根据 API schema 进行客户端编程使用的规则说明,工具和例子

具体的工作流程:

  1. 设计阶段
    • 需求收集阶段:平台产品与各端产品人员一起进行需求决策(必须要有平台产品的角色)
    • 设计阶段:平台产品与开发人员一起进行接口设计,产出 DSL schema。框架自动生成配套的工具,Demo,初步的文档等等
    • 实现阶段:开发人员根据公开获取的 DSL schema 进行开发
    • 测试阶段:测试人员根据公开获取 DSL schema 进行测试
    • 使用阶段:使用方根据公开获取 DSL schema 进行使用
    • 线上运行阶段:各方都可以根据公开获取的 DSL api 获得每个 API 的设计原则,实现细节,测试用例,最佳使用方式,以及当前的运行状态(如被降级,出问题等)。如果 API 有过更新或升级,则可以获得每次升级的需求,改动点等
  2. 调整阶段
    • 需求收集阶段:平台产品收集需求,进行决策
    • 设计阶段:平台产品与开发人员一起进行接口调整设计,产出 DSL schema。框架自动修改已有的配套工具,Demo,文档等
    • 实现阶段:开发人员根据更新记录,改动点等信息进行实现
    • 测试阶段:测试人员根据更新记录,改动点等信息进行测试
    • 使用阶段:使用方根据更新记录,改动点等信息进行使用方式修改
    • 线上运行阶段:各方都可以根据公开获取的 DSL api 获取该 API 的每次升级的更新记录,改动点

示例

假设 API V3 的框架已经开发完成。以 /3/users/show.json 接口为例:

  1. 需求收集阶段:需求明确为:展示用户基本信息
  2. 设计阶段(示例):(where goes models? pojo?)
    • 在 /3/ 和 /3/users/ 的返回结果里,增加 /3/users/show 这一条目。增加后的例子:

    /3/: {"result":"OK"; "version":3; "desc":"Weibo API Version 3, API index"; "list":["/3/users/", "/3/friendships/", "/3/status/", "/3/comments/"]}

    /3/users/:{"result":"OK"; "version":3; "desc":"Weibo API Version 3, API index, user section"; "list":["/3/users/show", "/3/users/show_batch"]}

    • /3/users/show.api 接口说明(聚合下面所有的?)
    • /3/users/show.desc 接口描述

    {"result":"OK"; "desc":"展示用户基本信息"; "..."}

    • /3/users/show.method 接口调用方式说明,http get/post,rpc 等

    {"result":"OK"; "method":{"http_get":{"url":"http://api.weibo.com/3/user/show.json"; "..."}; "rpc_get":{"url":"motan://api.weibo.com/3/user/show.json"}}}

    • /3/users/show.constraint 接口约束说明,转码,频率限制,注意事项等

    {"result":"OK"; "char":"UTF8"; "html_escape":true; "rate_limit":10000; "must_login":true; "..."}

    • /3/users/show.params 接口参数说明

    {"result":"OK"; "params":{"source":"the source"; "uid":""; "screen_name":""; "has_extend":""; "..."}}

    • /3/users/show.output 接口正常输出说明

    {"result":"OK"; "output":{}}

    • /3/users/show.errors 接口错误输出说明

    {"result":"OK"; "errors":{}}

    • /3/users/show.example 接口使用例子(建议用法),包括一个真实可运行(沙箱环境,可以直接拷贝到curl或其它使用方式进行测试)的接口调用及返回例子

    {"result":"OK"; "example":{}}

    • /3/users/show.status 接口状态(当前,或指定时间段),SLA 数字等

    {"result":"OK"; "status":"succ"; "SLA":{"%90":"3ms"; "99%":"8ms"; "99.9%":"32ms"; "99.99%":"79ms"}}

  3. 实现阶段:
  4. 测试阶段:
  5. 使用阶段:

    根据 example 给的例子进行使用

  6. 升级阶段:
    • /3/users/show.update 接口所有升级说明,改动点等(小版本化?)
  7. 线上运行阶段:

未完,待续。

原创版权所有,由于未完成,请勿转载,多谢!

发表评论