Learn API Basics

What’s an API?

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

Application Security 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 Application Security via its API to perform basic actions. These actions allow us to automate functionality within Application Security that would normally be considered manual.

There are several basic API concepts that are applicable to the Application Security 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 Application Security.

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 Application Security, 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 Application Security API requests are for authorization and content-type.

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

The X-Api-Key header allows authentication to the Application Security 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 Application Security 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 Application Security 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.

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 Application Security 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:

{"name": "Name 1","description": "This is a description.", "type": "Type 1"}

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.