公开记录开放API是一种好习惯吗？

Question

每个人都可以肯定开放API的优点和缺点。

但是公开记录开放API（要求对其请求进行身份验证）是好是坏做法？

通过公开文档，我的意思是创建一个文档，以显示API可以接收的请求主体的结构，并为所有这些字段提供描述。

例如，给定端点my-public.url/myendpoint/myresource，并提供可用的PUT，POST，DELETE和GET http请求有一个静态页面my-public.url/document/myendpoint其中显示了所有可接受的http请求以及执行请求所需的标题和请求正文的描述。

一方面，这将帮助外部开发人员轻松使用API​​，但是另一方面，如果有人以某种方式获得访问权限，则他们很容易发出请求并破坏系统，因为给出了API。

Answer 1

您可以从风险角度看待这一点。由于您提到的原因，提供API的公共文档会带来风险，这可能会帮助攻击者。另一方面，安全始终是一种平衡，提供文档可以帮助您的用户（甚至是您的用户）。

此外，您也不应该凭空实现安全性。攻击者应该知道事情的运行方式，但是，实际上，事实并非如此。

由于提供公共文档有风险，因此您必须以某种方式对待它。您可以冒险做几件事，例如，您可以接受它（不做任何事情），消除它（在这种情况下不提供文档）或减轻风险。

减轻这种风险将意味着您要做一些其他事情，以减少利用漏洞的可能性，或减少影响。例如，可以通过以下方式来降低可能性：更好地控制软件开发方式，围绕身份验证和授权功能添加自动测试，向组合中添加静态代码分析器等等。可以通过将逻辑层分开的良好体系结构，入侵检测/防御系统，甚至是单租户而不是多租户来减少影响。

最后，一切都取决于您要承担的风险，而这完全取决于您。有了适当的控件，可以提供公共文档-您还能期望用户如何使用api？问题是什么是“适当的”控制，这取决于您的风险偏好。

Answer 2

由于公开记录了文档，因此

应用程序的API中的风险完全没有增加。

以下是我想到的一些原因，

• 如果您使用的是基于浏览器的客户端，那么任何有知识来检查浏览器开发人员工具的 NETWORK 标签的人都可以找到您的API详细信息。
• 如果有任何使用您的API的移动客户端，则可以使用WireShark之类的应用程序轻松查看请求信息。最著名的API测试器应用程序POSTMAN也支持这种功能。

借助上述工具，任何人都有可能了解您的API详细信息。

公共文档的优势

• API使用者可以直接访问您的公共API文档，这显然可以节省API开发人员与消费者之间的沟通时间。 （基于版本的API（和文档）在更改现有版本时会非常有帮助）
• 创建Postman Collections之类的API演示/测试工具包将帮助API使用者轻松地测试和使用API​​。

为减少应用程序中的风险，您需要注意以下几点。

• 身份验证-登录凭据/访问令牌/ API密钥
• 授权-对正在访问/修改的任何资源进行访问检查。
• API速率限制-为避免DOS攻击。