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,
   ...
 }
}