Technical overview of REST API upgrade to 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:

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

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

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