学习API基础知识

一个API是什么?

应用程序编程接口(API)允许应用程序相互连接。API允许你用定义的语言与其他web组件交互，以请求或执行API可用服务的操作。

InsightAppSec利用RESTful API，它比其他API(如SOAP API)更轻量级，使用的带宽更少。

API格式化

在本例中，我们将通过InsightAppSec的API与它进行通信，以执行基本操作。这些操作允许我们在InsightAppSec中自动化通常被认为是手动的功能。

有几个基本的API概念也适用于InsightAppSec API。在使用API以更好地理解最佳实践之前，回顾一下这些概念是有好处的。

方法

方法是可以在API调用上下文中执行的不同类型的操作。换句话说，它决定在指定的资源上执行什么操作。在整个项目的示例中，有四个常用的API方法。

得到—用于检索信息，不用于修改信息。例如，对Get Apps端点的调用将从InsightAppSec返回一个应用程序列表及其相关细节。

帖子—根据用户提供的数据，创建新的资源。例如，对Create Blackout端点的调用将导致在InsightAppSec中根据所提供的数据创建一个全新的Blackout。

把—基于用户提供的某个标识符更新现有资源。例如，对Update Scan Config端点的调用需要指定扫描配置ID，并将导致根据提供的数据修改该配置。

删除—用于删除资源。例如，对Delete Schedule端点的调用需要一个Schedule ID，并将导致相关的Schedule被删除。请谨慎使用，因为它可能导致永久的数据丢失。

头

在API请求中使用头来提供关于API调用本身的附加信息。这可能包括与授权、缓存和调用中提供的内容类型相关的信息。InsightAppSec API请求中常用的两个头用于授权和内容类型。

         

          

           
          
         

          

           

            1
           headers = {"X-Api-Key": api_key， "Content-Type": "application/json"}
          

的X-Api-Keyheader允许对InsightAppSec API进行身份验证，而内容类型header指定将在请求中提供一个JSON主体。

参数

参数是API调用的另一个变量部分。参数是可以在API请求中提供的附加字段，用于指定特定的资源，或以其他方式影响调用的结果。

例如，当调用InsightAppSec Get漏洞端点时，必须提供一个漏洞ID来指定要检索的漏洞。如果没有这个参数，API将无法确定返回哪个漏洞。

在InsightAppSec API调用的上下文中可用的另一个参数是排序．添加排序参数将导致响应被相应地排序。例如，当通过Get scans端点检索扫描时，排序可以如下使用，指定扫描应该按照扫描的提交时间降序返回。

         

          

           
          
         

          

           

            1
           sort = scan.submit_time DESC
          

身体

请求体是一个键值对列表，用于在进行API调用时发送信息。身体通常需要帖子和把请求指定有关正在创建或更新的资源的信息。

例如，当使用InsightAppSec Create Blackout端点时，必须提供一个主体，以便API知道在创建Blackout时要使用哪些细节。这包括名称和中断发生的时间等信息，以及与之关联的应用程序(如果有的话)。

JSON主体示例通常如下所示:

         

          

           
          
         

          

           

            1
           ｛
          
          

           

            2
           “名称”:“1”,
          
          

           

            3.
           "description": "This is a description."，
          
          

           

            4
           “类型”:“1型”
          
          

           

            5
           ｝
          

冒号之前的字段是键，冒号之后的字段是值。结果是创建或更新一个资源，每个字段都被赋予指定的值。

主体中所需的数据类型将根据所使用的端点而变化，因为在不同类型的资源之间总是存在不同的字段。

InsightAppSec API的例子

在这个项目的样品目录中，我们获取了几个InsightAppSec API端点，并在Python和PowerShell中为它们创建了简单的示例脚本。

对于这两个Python和PowerShell，随附的指南涵盖了常用的InsightAppSec API概念和使用该API时的最佳实践。阅读本指南有助于更好地理解参数和分页等重复出现的概念。

每个示例都包含一个脚本，演示该端点的使用。每个脚本都处于工作状态，这意味着可以执行它来检索或修改现有的InsightAppSec数据。所需要的只是一个InsightAppSec API密钥，以及该端点上下文中相关的任何参数。

每个示例中还包含一个README，详细介绍了该端点的配置和使用。这包括关于格式化端点URL、参数以及如何处理在API调用中接收到的响应的指导。跟随此README了解如何编写使用该端点的脚本。