open api guidelines

概述

考虑到组织级对RESTful风格整体接受度较低，应该会实际实施介于1到2之间的成熟度模型

• 【必须】所有的对外的接口均使用HTTP协议，body规格为json（服务端至少支持识别content-type: application/json）
• 【推荐】参考通常意义上的RESTful风格进行设计，即推荐更多的使用HTTP自身的语义化能力（谓词、状态码、header段），而不是仅把HTTP当传输层协议
  • http body payload 内容和 http protocol 规范（主要也是rfc7231）适用的范围，均由具体业务接口（集）来完成定义
  • 但建议基于RMM的价值来进行深入的设计思考，使接口规则和通用设计目标（解耦、简约、表达力）趋于一致：
    1. 不要低于level 1，即系统要具备基本的分治设计能力
    2. 尽量达到level 2，使用标准的谓词和（HTTP 响应首行中）状态码来移除不必要的HTTP协议基础上的扩展设计，包括且不限于幂等约束、RFC中定义的的谓词和状态变迁等等，简单的来说就是减少重复造轮子，减少冗余设计
    3. 适度引入level 3，运用超媒体的能力使得API具备更强的自文档描述和服务被发现的能力
  • 整体来说，遵循以下原则
    • REST 模型成熟度目标为level 2，即识别HTTP协议谓词
    • 鼓励level 3，但需自行约定 HATEOAS 建模细节，建议至少包括rel和href，其中ref参考
  • 基于RMM level 2+ 进行设计的样例
• 对于http response payload的约束
  • JSON顶层为可能包含的字段有三个：content，links和error
    • 根据返回码不同而不同
    • 其中links如果接口设计的REST成熟度为level 3时存在
  • 不在顶层约束中设计http之外的code，也不建议使用额外的码表来管理扩展状态，一般来说只有错误时可能有潜在需要，可根据业务情况在error中自行添加
  • content为JSON的object，规格根据业务自定
  • 如content中返回集合数据，必需要有分页（pagination）设计，下辖两个字段
    • total，number（整型），表示不分页的集合总数
    • payload，array，数据集合内容
• pagination parameter约定
  • 客户端请求参数为per_page和page，表示返回的结果集大小，以及按这个大小分页是第几页
  • per_page和page均可以省略，省略时认为缺省值分别是10和1
  • per_page超过服务端能处理的最大值时，按服务端最大值返回
  • page值给出小于1则按1返回，给出的值大于指定per_page的最大页码值，则返回最后一页

参考

• PayPal
• Microsoft
• M$ Azure
• RMM，译文，另一个译文

样例

一组样例（以level 2为设计目标的，向level 3看齐的设计），包含集合对象的获取，单个对象的增删改查（待添加：批量增删改，条件查询等）

注意实际实施的整体风格大致会介于level 1 到 2之间