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.
substringof
is no longer available; in v4, you should usecontains
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
- 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
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.