Learn API Basics

What's an API?

An application programming interface, or API, allows applications to connect with each other. APIs let you to interact with other web components in a defined language in order to request or execute actions of the API's available services.

InsightAppSec leverages a RESTful API, which is more lightweight and uses less bandwidth than other APIs, such as SOAP APIs.

API Formatting

In this case, we'll be communicating with InsightAppSec via its API to perform basic actions. These actions allow us to automate functionality within InsightAppSec that would normally be considered manual.

There are several basic API concepts that are applicable to the InsightAppSec API, as well. It can be beneficial to review these concepts before utilizing the API to gain a better understanding of best practices.

Methods

Methods are different types of actions that can be performed in the context of an API call. In other words, it determines what operation will be performed upon the specified resource. There are four common API methods that are used in the examples throughout this project.

GET - Used for retrieving information, and NOT for modifying it. For example, a call to the Get Apps endpoint would return a list of applications and their associated details from InsightAppSec.

POST - Used to create new resources, based on data the user provides. For example, a call to the Create Blackout endpoint would result in a brand new blackout being created in InsightAppSec, based on the data provided.

PUT - Used to update an existing resource, based on some identifier that the user provides. For example, a call to the Update Scan Config endpoint requires a scan config ID to be specified, and would result in that config being modified based on the data provided.

DELETE - Used for deleting resources. For example, a call to the Delete Schedule endpoint requires a schedule ID and would result in the associated schedule being deleted. Use with caution, as it can result in the permanent loss of data.

Headers

Headers are used in API requests to supply additional information about the API call itself. This can include info relating to authorization, caching, and the type of content being supplied in the call. A couple headers commonly used in InsightAppSec API requests are for authorization and content-type.

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

The X-Api-Key header allows authentication to the InsightAppSec API, while the Content-Type header specifies that a JSON body will be supplied in the request.

Parameters

Parameters are another variable part of an API call. A parameter is an additional field that can be supplied in an API request to specify a particular resource, or otherwise influence the results of the call.

For instance, when making a call to the InsightAppSec Get Vulnerability endpoint, a vulnerability ID must be provided to specify the vulnerability to retrieve. Without that parameter, the API would not be able to determine which vulnerability to return.

Another parameter available in the context of InsightAppSec API calls is sort. Adding the sort parameter to a request will result in the response being sorted accordingly. For example, when retrieving scans via the Get Scans endpoint, sort could be used as below to specify that scans should be returned in descending order of the scan's submit time.

 
1
sort=scan.submit_time,DESC

Body

A request body is a list of key-value pairs used to send information when making an API call. A body is typically required with POST and PUT requests to specify info about the resource that is being created or updated.

For instance, when using the InsightAppSec Create Blackout endpoint, a body must be provided so the API knows what details to use when creating the blackout. This includes information like the name and the time at which the blackout occurs, as well as the application it's associated with (if any).

An example JSON body typically resembles the following:

 
1
{
2
  "name": "Name 1",
3
  "description": "This is a description.",
4
  "type": "Type 1"
5
}

The fields before the colon are the keys, while the fields afterwards are the values. The result is the creation or updating of a resource with each field being given its specified value.

The type of data required in the body will vary based on the endpoint being utilized, as there will always be fields that differ between different types of resources.

InsightAppSec API Examples

In this project's samples directory, we have taken several InsightAppSec API endpoints and created simple example scripts for them in Python and PowerShell.

For both Python and PowerShell, there is an accompanying guide that covers general InsightAppSec API concepts and best practices when it comes to using the API. It can be helpful to start with this guide to gain a better understanding of recurring concepts like parameters and pagination.

Each example includes a script that demonstrates the use of that endpoint. Every script is in a working state, meaning that it can be executed to retrieve or modify existing InsightAppSec data. All that's needed is an InsightAppSec API key, and any parameters relevant within the context of that endpoint.

Also included with each example is a README that walks through the configuration and usage of that endpoint in detail. This includes guidance on formatting the endpoint URL, parameters, and how to process the response received in the API call. Follow along with this README to get a step-by-step walkthrough of writing a script to utilize that endpoint.