Technical overview of REST API upgrade to v4

Version 4.0 of the REST API brings a host of enhancements, optimizations, and improvements over the previous version (v2). API v4 maintains compatibility by using the same access token as v2, facilitating a gradual migration of your code to v4 while continuing to use the existing token. Notably, the path prefix for API v4 has changed from "/api/v2" to "/api/v4/". While many functions retain their names and models, ensuring a straightforward transition from "v2" to "v4," some functions have undergone modifications. This topic serves as a technical guide, outlining the primary changes introduced in API v4.

OData version upgrade

The API now utilizes OData v4 instead of OData v3. This upgrade introduces advanced querying capabilities, including support for powerful aggregations on data.

Impact on Users:

  • Users can leverage more complex queries for precise data retrieval.
  • Existing queries based on OData v3 syntax need to be updated to align with the OData v4 standard.
Here are some examples of changes between OData v3 and v4 in $filter expression:
  • substringof is no longer available; in v4, you should use contains instead.
  • The Guid literal was changed: guid’971314e0-b891-4d2e-b672-0dc37885bb0a’971314e0-b891-4d2e-b672-0dc37885bb0a
  • The DateTime literal was changed: DateTime'2024-07-31T07:30:00' 2024-07-31T07:30:00z

Page results for collection functions

Functions returning collections now offer a paged result, which includes an optional total count.

Responses will adhere to the following format:

{
 "Items": [
 {
 Item1 ... 
 },
 {
 Item2 ... 
 }
 ],
 "Count": 2 //Optional - appears only if query option $count=true was provided 
}

In API v2, many functions that return a collection have two versions: one that returns a collection of objects and another that returns a page result for the objects. The advantage of the page result is that if $top and $skip are used to retrieve a single page, the total count of the objects will be included with the data, saving an additional request for the count.

In API v4, functions that return objects directly are omitted. These functions consistently provide data in PageResult format. The Count is optional and is only returned if $count=true is added to the query options.

For example, in API v2, there are two functions - /api/V2/Apps, which returns the result in regular format (array of objects) and /api/V2/Apps/GetAsPage, which returns the result in page format with count.

In v4, there is only one function - /api/v4/Apps, which returns the result in page format, and the count is optional. Note that if count is not required, it is more efficient not to request it.

Removal of redundant functions

Functions returning specific objects have been removed in favor of applying filters for a specific object id to functions returning collections.

Functions that aggregate objects are no longer required since this functionality is now available using OData v4 ($apply query option).

Example:

GET /api/v2/Scans/CountByUser was not added to v4.

Same functionality can be achieved by the following URL:

GET /api/v4/Scans?$apply=groupby((CreatedBy/Id,CreatedBy/UserName,CreatedBy/FirstName,CreatedBy/LastName,CreatedBy/Email), aggregate($count as Count))

Additional similar functions that were not added to v4 for the same reason:

/api/v2/Scans/CountByStatus

/api/v2/Scans/CountByTechnology

/api/V2/Users/Count

/api/v2/Issues/CountBySeverity/{scope}/{scopeId}

/api/v2/Issues/CountByStatus/{scope}/{scopeId}

/api/V2/AssetGroups/Count

Change in terms for scan technologies

The terms used for scan technologies were changed in API v4:
  • DynamicAnalyzer ⇒ Dast
  • StaticAnalyzer ⇒ Sast
  • IASTAnalyzer ⇒ Iast
  • ScaAnalyzer ⇒ Sca

These changes affected the following API functions under the Scans section:

  • GET /api/v2/Scans/DynamicAnalyzer/{scanId} ⇒ /api/v4/Scans/Dast/{scanId}
  • GET /api/v2/Scans/StaticAnalyzer/{scanId} ⇒ /api/v4/Scans/Sast/{scanId}
  • GET /api/v2/Scans/ScaAnalyzer/{scanId} ⇒ /api/v4/Scans/Sca/{scanId}
  • GET /api/v2/Scans/StaticAnalyzerExecution/{executionId} ⇒ /api/v4/Scans/SastExecution/{executionId}
  • GET /api/v2/Scans/DynamicAnalyzerExecution/{executionId} ⇒ /api/v4/Scans/DastExecution/{executionId}
  • GET /api/v2/Scans/DynamicAnalyzerScanFile/{executionId} ⇒ /api/v4/Scans/DastScanFile/{executionId}
  • POST /api/v2/Scans/StaticAnalyzer ⇒ /api/v4/Scans/Sast
  • POST /api/v2/Scans/DynamicAnalyzerUploadedResultsFromFile ⇒ /api/v4/Scans/DastScanResults
  • POST /api/v2/Scans/IASTAnalyzer ⇒ /api/v4/Scans/Iast

To create DAST scans, the three functions from API v2 were consolidated into a single function that exposes all the options. Note that the model required for the new function in v4 differs from the models in v2. See API documentation for more information.

The following three functions:

POST /api/v2/Scans/DynamicAnalyzer

POST /api/v2/Scans/DynamicAnalyzerWithFile

POST /api/v2/Scans/DynamicAnalyzerWithFiles

Merged into one function:

POST /api/v4/Scans/Dast

Change in issue model

Few changes were made to the issue model (returned from GET /api/v4/Issues/{scope}/{scopeId}):
  • The types of “Id” and “ApplicationId” were changed from string to guid. It's a minor adjustment, but it affects the format of the OData filters.
  • The following obsolete properties have been removed from the model:AvailabilityImpact, Classification, ConfidentialityImpact, Authentication, AccessComplexity, AccessVector, ProjectName, Protocol, RemediationLevel, ReportConfidence, NessusPluginId, FixRecommendation, IntegrityImpact, Summary, WhiteHatSecVulnId, StepsToReproduce, Description ,Exploitability, ApplicationName, FriendlyId.