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

Mise à niveau de la version d'OData

L'API utilise désormais OData version 4 au lieu d'OData version 3. 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 collection

Les fonctions qui renvoient des collections offrent désormais un résultat paginé, 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 version 2, de nombreuses fonctions qui renvoient une collection comptent 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 de la page est que si les paramètres $top et $skip sont utilisés pour récupérer une seule page, le nombre total d'objets est inclus avec les données, ce qui évite d'effectuer une requête supplémentaire pour connaître le nombre.

Dans l'API version 4, les fonctions qui renvoient directement des objets sont exclues. 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, l'API version 2 compte deux fonctions, /api/V2/Apps, qui renvoie le résultat au format standard (tableau d'objets) et /api/V2/Apps/GetAsPage, qui renvoie le résultat au format de page avec le nombre.

La version 4 ne compte 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 comptage 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 propre 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 version 4 ($Apply query option).

Exemple :

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

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 version 4 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

Changement de terminologie pour les technologies d'examen

Ces modifications affectent les fonctions suivantes de l'API dans la section Examens :

Pour créer des examens DAST, les trois fonctions de l'API version 2 ont été regroupées en une seule fonction qui affiche toutes les options. Notez que le modèle requis pour la nouvelle fonction dans la version 4 diffère des modèles de la version 2. Pour en savoir plus, voir la documentation de l'API.

Les trois fonctions suivantes :

POST /api/v2/Scans/DynamicAnalyzer

POST /api/v2/Scans/DynamicAnalyzerWithFile

POST /api/v2/Scans/DynamicAnalyzerWithFiles

Fusionnées en une seule fonction :

POST /api/v4/Scans/Dast

Modification du modèle de problème