我的新书《Android App开发入门与实战》已于2020年8月由人民邮电出版社出版,欢迎购买。点击进入详情
“应用程序编程接口”或 API 是指各种软件服务之间的通信通道。传输请求和响应的应用程序分别称为客户端和服务器。
有不同类型的API 协议:
什么是 API?(来源:RapidAPI)
作为软件工程师,我们的大部分日常工作都会使用或创建 REST API。系统之间通信的标准方法是通过 API。因此,正确构建 REST API 以避免将来出现问题至关重要。定义良好的 API 应该易于使用、简洁且不易误用。
以下是一些一般性建议:
? 不应在端点路径中使用动词。相反,路径名应包含标识我们正在访问或更改的端点所属对象的名词。
例如,不要使用/getAllClients
来获取所有客户端,而是使用/clients
.
? 对资源名词使用复数形式,因为这适合所有类型的端点。
例如,不要使用/employee/:id/
,而是使用/employees/:id/
.
? 当我们说保持一致时,这意味着是可预测的。当我们定义了一个端点时,其他端点的行为也应? ? ? 该类似。因此,对资源使用相同的情况,对所有端点使用相同的身份验证方法,相同的标头,? ? ? 相同的状态代码等。
? 我们应该按原样将所有端点命名为面向资源的。如果我们想为用户定义一个API,我们会将其描? ? 述为:
/users
/users/124
因此,第一个 API 获取所有用户,第二个 API 获取特定用户。
? 这一点超级重要。HTTP 状态码有很多,但我们通常只使用其中的一些。不要使用太多,但对? ? ? API 中的相同结果使用相同的状态代码,例如,
HTTP 状态代码
? REST API 应接受 JSON 作为请求负载并使用JSON进行响应,因为它是传输数据的标准。然? ? ? 而,仅仅返回一个 JSON 格式的字符串是不够的;我们需要将 Content-Type 标头指定为? ? ? ? ? ? ? application/JSON。唯一的例外是我们尝试在客户端和服务器之间发送和接收文件。
? 在这里,我们希望消除发生错误时的任何混乱。我们必须正确处理错误并返回指示发生了什么? ? ? 的响应代码(从400 到 5xx 错误)。我们需要在响应正文中返回一些详细信息以及状态代码。
? 我们希望客户端和服务器之间的所有通信都受到保护,这意味着我们需要始终使用 SSL/TLS,? ? 无一例外。此外,允许通过 API 密钥进行身份验证,该密钥应使用带有到期日期的自定义? ? ? ? ? ? HTTP标头进行传递。
? 如果我们的 API 需要返回大量数据,请使用分页,因为这将使我们的 API 面向未来。此处推荐? ? 使用page
和page_size
例如,/products?page=10&page_size=20
? 从第一个版本开始对 API 进行版本控制至关重要,因为我们的 API 可能有不同的用户。这将使? ? 我们的用户避免受到我们将来可能做出的更改的影响。API 版本可以通过 HTTP 标头或查询/路? ? 径参数传递。
例如,/products/v1/4
另外,不要忘记记录您的 API,因为 API 的好坏取决于其文档。文档应显示完整请求/响应周期的示例。在这里,我们可以使用OpenAPI定义作为事实来源。