使用 OAS（OpenAPI标准）来描述 Web API

无论哪种类型的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 的目标, 最基本的要对以下方面有深刻, 精准的认识: 

1. Who, 谁可以使用这个API? 

2. What, 用户拿这个API能做什么事?  

3. How, 用户如何做这件事? 

4. What need, 用户想要做这件事的话还需要什么? 

5. What return, 用户会得到什么? 

1.就是指API的用户, 4,5分别表示输入输出.  

针对2, 3解释一下 

通常针对2.What(用户拿API能做什么)可以导致(分解)多个3.How(多个步骤), 这样的话每个步骤就是一个API的目标. 

比如说, 用户想去淘宝买一个商品, 那么怎么买? 首先需要把商品添加到购物车, 然后再结账. 那么这个API就应该有两个目标: 添加商品到购物车, 以及 结账. 

如果不这样分解到话, 通常设计出的API会缺失一些目标. 

针对1, 也解释一下 

首先应该识别出不同种类的用户, 这里的用户可能是人, 也可能是其他的程序. 通常通过检查输入和输出就可以识别出用户. 

总结一下就6个方面: 

• 用户 

• 能做什么 

• 如何做 - 分解步骤 

• 输入 

• 输出 

• 目标 

避免从开发者角度设计API 

这部分包含几个方面. 包括: 

• 开发者所在公司的组织结构(参考康威定律) 

• 数据, 例如数据使用了开发者所在公司内部的一些专有术语, 或者干脆把内部数据库模型暴露了出来. 

• 不要暴露实现细节, 避免受到业务逻辑实现细节的影响 

• 避免受到软件架构的影响, 比如说在开发者公司内部查询产品名称和产品价格是两个API, 那么给用户使用的API必须整合一下, 不能让用户分两步查询. 

最重要的还是要时刻牢记, 你所设计的这些东西都是用户真正需要的吗? 

下面切入正题: 

使用API描述格式来描述API