RESTful API Service Version 2.0
This section describes differences between RESTful API service version 2 and RESTful API service version 1:
Both RESTful API version 2 and RESTful API version 1 are available simultaneously, and the remainder of this guide shows version 1 examples. Use the service version portion of the request URI (v1
or v2
) to select the REST API version that you want to use.
Scriptable Values
RESTful API version 2 operations always return scriptable values. A scriptable value has the same stable form for each type of property.
RESTful API version 1 operations often return a scriptable value, but not always. For example, RESTful API version 1 sometimes returns datetime strings in full Javascript date format and sometimes returns datetime strings in the ISO 8601 datetime format. RESTful API version 2 always returns datetime strings in the ISO 8601 datetime format.
In the following example, the GET /api/system/v1/updates
operation returns datetime strings in full Javascript date format, and the GET /api/system/v2/updates
operation returns datetime strings in the ISO 8601 datetime format:
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" }] }
Consistent Values
RESTful API version 1 operations sometimes return different values for the same property, depending on how the property is accessed. RESTful API version 2 operations return consistent values, independent of how the property is accessed.
In the following example, when all replication actions are listed, the value of the max_bandwidth
property returns as -1
:
GET /api/storage/v1/replication/actions
{
"actions": [{
"id": "71b1b8b9-9c57-c969-aab9-f96d5f4e5d54",
...
"max_bandwidth": -1,
...
}]
}
When only one replication action is specified, the value of the max_bandwidth
property returns as 0
, even though the underlying value is unchanged:
GET /api/storage/v1/replication/actions/71b1b8b9-9c57-c969-aab9-f96d5f4e5d54 { "action": { "id": "71b1b8b9-9c57-c969-aab9-f96d5f4e5d54", ... "max_bandwidth": 0, ... } }
RESTful API version 2 operations always return the same value for a particular property, regardless of how that property value is accessed:
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, ... } }