Présentation technique de la mise à niveau de l'API REST vers la v4

Mise à niveau de la version OData

L'API utilise désormais OData v4 au lieu d'OData v3. Cette mise à niveau introduit des fonctionnalités avancées d'interrogation, notamment la prise en charge de puissantes agrégations de données.

Impact sur les utilisateurs :

Résultats de la page pour les fonctions de collecte

Les fonctions qui renvoient des collections offrent désormais un résultat en pages, qui inclut un nombre total facultatif.

Les réponses seront conformes au format suivant :

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

Dans l'API v2, de nombreuses fonctions qui renvoient une collection ont deux versions : l'une qui renvoie une collection d'objets et l'autre qui renvoie un résultat de page pour les objets. L'avantage du résultat en pages est que si $top et $skip sont utilisés pour récupérer une seule page, le nombre total des objets sera inclus avec les données, ce qui permettra d'enregistrer une demande supplémentaire pour le nombre.

Dans l'API v4, les fonctions qui renvoient directement des objets sont omises. Ces fonctions fournissent systématiquement des données au format PageResult. Le nombre est facultatif et n'est renvoyé que si $count=true est ajouté aux options de requête.

Par exemple, dans l'API v2, il existe deux fonctions - /api/V2/Apps, qui renvoie le résultat au format normal (tableau d'objets) et /api/V2/Apps/GetAsPage, qui renvoie le résultat au format de page avec le nombre.

Dans la v4, il n'y a qu'une seule fonction - /api/v4/Apps, qui renvoie le résultat au format de page, et le nombre est facultatif. Notez que si le nombre n'est pas nécessaire, il est plus efficace de ne pas le demander.

Suppression des fonctions redondantes

Les fonctions renvoyant des objets spécifiques ont été supprimées afin d'appliquer des filtres pour un ID d'objet spécifique aux fonctions renvoyant des collections.

Les fonctions qui regroupent les objets ne sont plus nécessaires, car cette fonctionnalité est désormais disponible à l'aide d'OData v4 ($apply query option).

Exemple :

GET /api/v2/Scans/CountByUser n'a pas été ajouté à la v4.

Les mêmes fonctionnalités peuvent être obtenues à l'aide de l'URL suivante :

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

Autres fonctions similaires qui n'ont pas été ajoutées à la v4 pour la même raison :

/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

Modification des termes pour les technologies d'examen

Ces modifications ont affecté les fonctions d'API suivantes dans la section Examens :

Pour créer des examens DAST, les trois fonctions de l'API v2 ont été regroupées en une seule fonction qui expose toutes les options. Notez que le modèle requis pour la nouvelle fonction dans la v4 diffère des modèles de la v2. Pour plus d'informations, consultez la documentation d'API.

Les trois fonctions suivantes :

POST /api/v2/Scans/DynamicAnalyzer

POST /api/v2/Scans/DynamicAnalyzerWithFile

POST /api/v2/Scans/DynamicAnalyzerWithFiles

Sont fusionnées en une seule fonction :

POST /api/v4/Scans/Dast

Modification du modèle de problème