The version 2 API was introduced in September 2015. This article is for people who are still using the version 1 API and are looking to update.
When migrating applications to the version 2 APIs it is important to understand the changes that have been made, both in the structure of the API and the format of the response.
Minor restructuring has taken place with the response format to group information about the related Bluemix organization, the following attributes have been removed:
They are replaced by the following corresponding attributes:
Device & Device Type Registration
In the version 1 API a device was registered by a HTTP POST to /api/v0001/devices with a body containing two required attributes:
In the version 1 API a device type was just a property of a device, there was no metadata about the device type. The version 2 API introduced a richer model that includes the ability to store information about the device types themselves, because of this a device cannot be registered until after a device type has been created.
A device type is created by a HTTP POST to /api/v0002/device/types with a body containing one required attribute:
After the device type has been created the device can be registered by a HTTP POST to /api/v0002/device/types/$myTypeId/devices with a body containing one required attribute:
Device information retrieval
To lookup the information about a device in the version 1 API you would issue a HTTP GET request to /api/v0001/devices/$myTypeId/$myDeviceId. In the version 2 API the GET request must be made to /api/v0002/device/types/$myTypeId/devices/$myDeviceId. The response format has also changed, the primary changes you need to be aware of is the rename of the following 3 attributes:
- uuid is now clientId
- type is now typeId
- id is now deviceId
Updating and removing devices
In the version 1 API the device resource URI was /api/v0001/devices/$myTypeId/$myDeviceId, as with the device information retrieval HTTP PUT and DELETE requests need to be sent to /api/v0002/device/types/$myTypeId/devices/$myDeviceId instead when working with the new version of the API. Updates to devices through the version 2 API also support partial updates, allowing you to submit only the information that has changed about the device rather than the entire device document.
Under the version 1 APIs there were two ways to get lists of devices.
A list of every device in your organization could be obtained with a HTTP GET request to /api/v0001/devices, in the version 2 API this request should instead go to /api/v0002/bulk/devices. The version 1 API returned a simple array of device records, the version 2 API provides additional metadata for the listing, and returns the actual device list in the results attribute of the response.
A list of every device of a certain type could be obtained with a HTTP GET request to /api/v0001/devices/$myTypeId, when updating to the version 2 of the API this request must be changed to /api/v0002/device/types/$myTypeId/devices. The same changes mentioned previously apply here as well, the device listing will be returned in the results attribute of the JSON response.
These are the main changes that an application developer will face when updating an existing application to utilize the version 2 platform API. The version 2 API also brings with it a wealth of new features to take advantage of, for full details of all the new features refer to the online documentation. We have a number of open source client libraries supporting multiple programming languages available in GitHub, all of which have full support for the current version 2 API.
If you have any questions about updating your own code to work with the version 2 APIs that were not covered here please post a question in dW Answers and we will do our best to assist you.