Cette section décrit les différences entre les versions 1 et 2 des services d'API RESTful :
Les versions 1 et 2 d'API RESTful sont disponibles simultanément. Le reste de ce guide montre des exemples de la version 1. Utilisez la partie de version du service de l'URI (v1 ou v2) de la demande pour sélectionner la version d'API REST souhaitée.
Les opérations effectuées avec la version 2 d'API RESTful renvoient toujours des valeurs scriptables. Une valeur scriptable a la même forme stable pour chaque type de propriété.
Les opérations effectuées avec la version 1 d'API RESTful renvoient souvent des valeurs scriptables, mais ce n'est pas systématique. Par exemple, la version 1 de l'API RESTful renvoie parfois des chaînes datetime dans un format de date Javascript complet ou un format date/heure ISO 8601. La version 2 renvoie toujours des chaînes datetime dans le format date/heure ISO 8601.
Dans l'exemple suivant, l'opération GET /api/system/v1/updates renvoie des chaînes datetime dans un format de date Javascript complet. L'opération GET /api/system/v2/updates renvoie des chaînes datetime dans le format date/heure ISO 8601 :
GET /api/system/v1/updates { "updates": [{ "status": "previous", "href": "/api/system/v1/updates/ak-nas@2013.06.05.4.0,1-1.7", "release_date": "Fri May 01 2015 20:13:00 GMT+0000 (UTC)", "install_date": "Tue Nov 15 2016 01:01:07 GMT+0000 (UTC)", "version": "2013.06.05.4.0,1-1.7", "date": "Fri May 01 2015 20:13:00 GMT+0000 (UTC)" }] } GET /api/system/v2/updates { "updates": [{ "status": "previous", "href": "/api/system/v2/updates/ak-nas@2013.06.05.4.0,1-1.7", "release_date": "2015-05-01T20:13:00Z", "install_date": "2016-11-15T01:01:07Z", "version": "2013.06.05.4.0,1-1.7", "date": "2015-05-01T20:13:00Z" }] }
Les opérations effectuées avec la version 1 d'API RESTful renvoient parfois des valeurs différentes pour la même propriété, en fonction du mode d'accès à celle-ci. Les opérations effectuées avec la version 2 d'API RESTful renvoient des valeurs cohérentes, indépendamment du mode d'accès à la propriété.
Dans l'exemple suivant, lorsque toutes les actions de réplication sont énumérées, la valeur renvoyée pour la propriété max_bandwidth est -1 :
GET /api/storage/v1/replication/actions { "actions": [{ "id": "71b1b8b9-9c57-c969-aab9-f96d5f4e5d54", ... "max_bandwidth": -1, ... }] }
Lorsqu'une seule action de réplication est spécifiée, la valeur renvoyée pour la propriété max_bandwidth est 0, même si la valeur sous-jacente est inchangée :
GET /api/storage/v1/replication/actions/71b1b8b9-9c57-c969-aab9-f96d5f4e5d54 { "action": { "id": "71b1b8b9-9c57-c969-aab9-f96d5f4e5d54", ... "max_bandwidth": 0, ... } }
Les opérations effectuées dans la version 2 d'API RESTful renvoient systématiquement la même valeur pour une propriété particulière, indépendamment du mode d'accès à la valeur de cette dernière :
GET /api/storage/v2/replication/actions { "actions": [{ "id": "71b1b8b9-9c57-c969-aab9-f96d5f4e5d54", ... "max_bandwidth": -1, ... }] } GET /api/storage/v2/replication/actions/71b1b8b9-9c57-c969-aab9-f96d5f4e5d54 { "action": { "id": "71b1b8b9-9c57-c969-aab9-f96d5f4e5d54", ... "max_bandwidth": -1, ... } }