Client Specification 2 is a recent update to the API interface. This update has been rolled out to address feedback from developers who have been working with the API. Issues had been raised about complexity of working with representations returned by the API in two areas: the RecycleBin contents and when using the 'X-Cloud-Depth' header.
The current documentation only documents the new interface.
Changes to the RecycleBin representation
Previously, it was not intuitive as to how to determine if a deleted object was a file or a container object. The behavior of the RecycleBin has been updated to directly indicate the type of the deleted object.
Changes when using the 'X-Cloud-Depth' header
The 'X-Cloud-Depth' request header provides an optimization to the retrieval of resources. When this header is specified on a GET request, any linked resources are retrieved in place. For certain resources, this caused confusion when the element expanded was named differently than the root of the resource when requested alone. The functionality of the system has been updated to insert an element, as a child of the linked element, which bears the same name as the stand-alone resource.
Frequently Asked Questions
Q: Why was this change implemented?
A: Based on feedback from a number of developers, it was decided to make these changes to improve the usability of the API. We believe that the new specification makes more sense and provides a cleaner interface.
Q: Is ‘Client Specification 1′ still available?
A: The original API specification continues to work when accessing the API, however the specification has been deprecated and should not be used in future development.
Q: When will the update be available at all providers?
A: An update to software providing the service has been implemented as a patch that each service provider must apply. Each service provider sets their own timetable for applying this patch based on their own internal processes. We expect all providers to support the new specification very soon.