作为后端工程师,多数情况都是给别人提供接口,写的好不好使你得重视起来。
最近我手头一些活,需要和外部公司对接,我们需要提供一个接口文档,这样可以节省双方时间、也可以防止后续扯皮。这是就要考验我的接口是否规范化。
顾名思义,接口是做什么的,是否准确、清晰?让使用这一眼就能知道这个接口在做什么,力求言简意赅。比如:查询用户信息,简单明了。
接口地址,也就是接口的 URL
路径。当别人调用你的接口,就是通过 URL
配合请求时参数来调用。比如: /api/user/queryById
。一般来说,接口地址的命名也要可以大概看出接口的作用,比如前面这个接口,它是作用使用:通过用户id查询用户信息。
除了接口路径,还需要指明接口的域名或IP。以 http 协议为例、端口是 8080,当我请求 javapub 的用户中心信息时:
请求方式常用的有如下几种:
这么多请求方式,多数中小公司只用 GET 和 POST
,可能还有些公司只用 POST
。但是选择合适的请求方式可以提升开发效率、并且让我们的接口更容易复用。
不管用哪种,一定要写清楚。
如果是非常简单的接口,通过接口名就可以了解个大概。如果是一些非常复杂的接口,就一定要添加详细说明文档,包括功能描述、请求参数、请求相应参数等信息。
力求言简意赅,通过入参、做了什么动作、返回哪些值。
接口文档需要提供接口示例,接口实例是为了帮助调用者理解接口的使用方法和调用流程,快速开始调试程序。一般是 CURL
格式的示例。
curl javapub.net.cn
随着功能开发的日趋完善,可能对接口做出修改更新,例如添加、删除时变更参数,或者修改返回值的格式。这些新变更可能影响用户的 API 使用体验,造成现有客户端无法使用。
https://javapub.net.cn:8080/api/user/v1/queryById
https://javapub.net.cn:8080/api/user/v2/queryById
如果接口发生了变更,接口文档也要做出相应调整,维护文档。比如错误码更新、参数类型变更等,要明确记录。
日期 | 变更内容 | 责任人 |
---|---|---|
2028-03-01 | 创建接口文档,定义基本数据结构。 | JavaPub |
2028-05-10 | V2.0用户中心接口更新 | 王哥 |
接口文档,要写清楚请求头信息,比如:有权限校验的接口请求,在请求头中 apiKey
。还有一些参数是 JSON 的,要设置 application/json
。
Accept: text/plain, text/html
。Authorization: Basic QzPhZGRpbjpvcGVuIHNlc2FtZQ==
Cookie
信息。gzip、deflate
等。有些接口参数涉及到隐私和敏感数据、需要参数加密做好脱敏处理和说明。此外,还要做好接口授权访问,防止出现拖库、击穿等P0问题。
在编写接口文档时,编写测试案例也要给出测试数据,包括请求参数和返回结果。让调用者有一个预期,节省沟通成本。
接口文档,一定要错误码,错误码作为程序重要的参考,让下游知道什么时候做什么动作。比如:当查询不到用户信息时,可以提示它跳转到注册页面。
错误码 | 名称 | 说明 |
---|---|---|
1001 | 参数错误 | 参数不合法 |
1002 | 数据库错误 | 数据库请求出错 |
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。