无论哪种类型的Web API, 都可能需要给其他开发者使用. 所以API的开发者体验是很重要的. API的开发者体验, 简写为 API DX (Developer Experience). 它包含很多东西, 例如如何使用API, 文档, 技术支持等等, 但是最重要的还是API的设计. 如果 API 设计的不好, 那么使用该API构建的软件就需要增加在时间,人力,金钱等方面的投入. 有时候API会被错用, 甚至带来毁灭性后果. 最后抱怨该API等用户越来越多, 慢慢的, 客户就会停止使用该API.
API的目的是让人们可以简单的使用它来达到自己的目的. 目前行业内有很多API风格, 例如: REST, gRPC, GraphQL, SOAP, RPC等等. 但是每个风格都遵循一些基本的设计原则.
用户就是上帝, 为用户设计API
和构建任何东西一样, 你需要一个计划, 你需要在真正做之前来决定你想要的是什么. API 设计也是一样的.
API 并不是用来盲目的暴露一些数据或业务处理能力. 它就像我们每天使用的任何形式的接口一样, 例如微波炉的操作按钮, 是来帮助用户完成他们的目标的. 所以需要从用户的视角来决定一个API的设计目标. 在整个设计过程中, 必须牢记以用户的视角去设计, 如果以开发者的角度去设计, 那么问题就大了.
如果以开发者的视角去设计的API, 那么通常的后果是开发出的API会很注重功能实现的过程和原理, 而不是用户如何能简单平滑的使用这个API来达到他们的目的. 所以一定要注重用户的需求, 而不要让内部实现细节, 原理什么的来骚扰用户. 最后再次强调, 要设计出让用户容易理解和容易使用的API.
所以 API 就是用户看到的, 它表示出用户能使用它做什么. API 的实现细节, 也就是如果完成的该功能的细节, 需要对用户隐藏.
识别 API 的目标
记住首先考虑用户的感受之后, 下面就需要考虑用户能拿它来做什么了, 也就是识别API的目标.
识别 API 的目标, 最基本的要对以下方面有深刻, 精准的认识:
-
Who, 谁可以使用这个API?
-
What, 用户拿这个API能做什么事?
-
How, 用户如何做这件事?
-
What need, 用户想要做这件事的话还需要什么?
-
What return, 用户会得到什么?
1.就是指API的用户, 4,5分别表示输入输出.
针对2, 3解释一下
通常针对2.What(用户拿API能做什么)可以导致(分解)多个3.How(多个步骤), 这样的话每个步骤就是一个API的目标.
比如说, 用户想去淘宝买一个商品, 那么怎么买? 首先需要把商品添加到购物车, 然后再结账. 那么这个API就应该有两个目标: 添加商品到购物车, 以及 结账.
如果不这样分解到话, 通常设计出的API会缺失一些目标.
针对1, 也解释一下
首先应该识别出不同种类的用户, 这里的用户可能是人, 也可能是其他的程序. 通常通过检查输入和输出就可以识别出用户.
总结一下就6个方面:
-
用户
-
能做什么
-
如何做 - 分解步骤
-
输入
-
输出
-
目标
避免从开发者角度设计API
这部分包含几个方面. 包括:
-
开发者所在公司的组织结构(参考康威定律)
-
数据, 例如数据使用了开发者所在公司内部的一些专有术语, 或者干脆把内部数据库模型暴露了出来.
-
不要暴露实现细节, 避免受到业务逻辑实现细节的影响
-
避免受到软件架构的影响, 比如说在开发者公司内部查询产品名称和产品价格是两个API, 那么给用户使用的API必须整合一下, 不能让用户分两步查询.
最重要的还是要时刻牢记, 你所设计的这些东西都是用户真正需要的吗?
下面切入正题:
使用API描述格式来描述API
这里我以RESTful风格的API为例. 想要了解使用ASP.NET Core 3.x 构建 RESTful API, 这里有一个教程(但是还没讲完) https://www.bilibili.com/video/av77957694/.
很多人使用Excel或者纸和笔来进行API的设计工作. 但是如果想要在设计阶段精准描述一个API, 尤其是它的数据, 那么最好使用一个结构化的工具, 例如API描述格式.
API描述格式会为API提供一个标准化的描述, 并且它很像代码. 它的优势主要有:
-
有助于在项目团队中共享设计
-
了解这种格式的人或者工具可以很简单的理解它.
针对REST而言, OpenAPI Specification(OAS) 就是一个非常流行API描述格式规范.
OAS
API描述格式是一种数据格式, 它的目标就是描述API.
而OAS (OpenAPI Specification)是一个与编程语言无关的REST API描述格式. 它是由 OAI (OpenAPI Initiative) 所提倡的. OAI 是Linux基金会下面的一个组织, 专注于提供与供应商无关的描述格式. 而OAS则是社区驱动的一种格式, 任何人都可以做贡献.
OAS vs Swagger
OAS 原来叫 Swagger Specification, 2015年11月这个格式被贡献给了OAI, 并在2016年1月更名为 OpenAPI Specification. Swagger 规范最后的2.0版本就变成了 OpenAPI 2.0. 目前最新的OAS 应该是3.0大版本
YAML
OAS文档可以使用YAML或JSON格式, 我使用YAML.
像写代码一样描述API
OAS文档就是一个文本文件, 可以纳入版本控制系统 ,例如 Git等. 所以在设计迭代的时候很容易进行版本管理和变化追踪.
编辑器
OAS有一个在线的专用编辑器: http://editor.swagger.io/
左边是代码编辑区域, 右边是渲染结果.
但是我更习惯于本地编辑器, 我使用VSCode, 并安装 Swagger Viewer 和 openapi-lint 两个插件.
共享API描述, 对API进行文档记录
OAS文档可以用来生成API对引用文档, 这个引用文档可以展示出所有可用的资源以及相应的操作. 通常我会使用Swagger UI, 它就是上图右侧的部分.
生成代码
使用API描述格式进行描述的API, 其代码也可以部分生成. 通常是一个代码骨架.
什么时候使用API描述格式
肯定是在设计接口如何表达API目标和概念, 以及数据的时候.
使用OAS来描述REST API的资源以及Action
创建OAS文档
建立一个products.yaml文件.
然后在里面输入 api 或 open等字符串, 会出现两个提示选项:
先选择下面那个选项, 其结果是:
-
第1行是Open API的版本
-
第4行 info 的 version 是指API的版本, 而info这个版本必须使用双引号括起来, 否则OAS解析器会把它当成数字, 从而导致文档验证失败(因为它的类型应该是字符串).
-
第5行 paths, paths属性应该包含该API可用的资源. 这里面使用 {} 仅仅是为了让文档验证通过, 因为我目前还没有写什么内容. 在YAML里, {} 表示一个空的对象, 而非空的对象则不需要这对大括号.
描述资源
为了描述products这个资源, 就需要填写paths属性:
这里description属性不是强制的, 但是它可以用来描述该资源.
描述资源的操作
OAS文档里描述的资源肯定包含一些操作, 否则文档就不合理.
看代码:
我为/products这个资源添加了一个GET Action (get属性), 然后我对这个get也进行了描述.
summary相当于是对这个Action的一个概括性描述, 而description则能提供更详细的描述信息.
这里description是支持多行文本的, 但是在YAML里面要想支持多行文本, 那么string属性必须以 | 管道符 开头.
注意, 这里第1行 openapi下面的波浪线表示文档验证失败.
在OAS文档里, 一个操作必须在responses属性里提供至少一个响应:
一个Action可能有多种响应结果, 每种可能的响应结果都要在responses属性中描述.
每个响应都以状态码进行标识, 并且必须包含一个description属性.
注意: 状态码数字必须用双引号括起来, 因为它的类型本应该是字符串, 而这里的200是一个数字.
下面我再添加一个POST Action: