飞书前OpenAPI治理者：好API设计是用户体验问题

有个朋友之前在飞书开放平台负责OpenAPI治理和审批，他说如果哪个API设计不合理，会被他喷回去。 我问他具体是怎么判断API设计好不好的，他说主要看几个维度：一是接口命名是否清晰，二是参数设计是否合理，三是错误码是否完善，四是文档是否易懂。 他举了个例子，有些开发者设计的API接口名特别长，比如「getUserInformationByUserIdAndDepartmentId」，这种命名虽然语义清晰，但太啰嗦了。好的设计应该是「getUser」，然后通过参数来过滤。 还有就是参数设计。有些API把所有参数都放在一个对象里，没有做分层。比如查询用户列表，应该把分页参数、过滤参数、排序参数分开，而不是全塞在一起。 错误码也是个容易被忽视的点。有些API只返回「参数错误」，但不告诉你是哪个参数错了。好的设计应该返回具体的错误信息，比如「userId参数格式错误，应该是数字类型」。 文档就更不用说了。有些API文档写得跟天书一样，看了半天不知道怎么用。好的文档应该有清晰的示例代码，让开发者能快速上手。 他说做API治理这几年，最大的感受就是：好的API设计不是技术问题，而是用户体验问题。你得站在开发者的角度去思考，怎么让他们用得舒服。 你们在用飞书开发的时候，有没有遇到过什么API设计不合理的地方？