RESTful API Nodes

Core Amazon Drive functionality

This API lets you create, read and update the contents in a customer's account. Nodes are the fundamental resource in Amazon Drive. They are used to represent different kinds of digital assets including files and folders. Nodes can be associated to other nodes in a parent-child relationship. Nodes can contain just metadata (i.e., when representing a folder) or it can contain metadata and binary content (i.e., when representing a photo). Nodes can be represented in a parent-child relationship, created, updated or trashed.

Response codes

The client passed in the invalid Auth token. Client should refresh the token and then try again.

403

Forbidden.

404

Resource not found.

500

Servers are not working as expected. The request is probably valid but needs to be requested again later.

503

Service Unavailable.

Partial Update File Metadata

To update partial file Metadata like name. Clients can optionally do a conditional partial update by passing an ETag, which was received in a previous response, in If-Match header.
The allowed fields to updates are name, labels, description.

Response codes

TThe client passed in the invalid Auth token. Client should refresh the token and then try again.

403

Forbidden.

404

Resource not found.

412

Precondition failed, if ETags do not match.

500

Servers are not working as expected. The request is probably valid but needs to be requested again later.

503

Service Unavailable.

Getting List of files

Retrieve list of all the available file metadata. The listing limit is 200 per page, response include nextToken which can be passed in as the startToken in the next request to get the next set of file metadata.

GET : /drive/v1/nodes?filters=kind:FILE

filters

optional

filters for request, see [filtering](#Filtering)

startToken

optional

nextToken from previous request for access more content, see [pagination](#Pagination)

sort

optional

to order the result in sorted manner, see [sorting](#Sorting)

limit

optional

default to 200. Limit the number of file metadata to be returned.

assetMapping

optional

default NONE, see [assetMapping](#AssetMapping)

tempLink

optional

default false, set true to include tempLink in response. If you try to get tempLink for the content types, you don’t have permission for, tempLink will not return in list nodes response.

Sample HTTP Response Headers

Response codes

The client passed in the invalid Auth token. Client should refresh the token and then try again.

403

Forbidden.

404

Resource not found.

500

Servers are not working as expected. The request is probably valid but needs to be requested again later.

503

Service Unavailable.

Assets

Assets provides various flavors of a File or Folder like thumbnails for images, trailers for videos, cover photo for a Folder. Asset resource is similar to File except its kind is ASSET and it can't have any children, otherwise it's just a binary bits stored in Amazon Drive along with its metadata and it have all same methods supported as for a File.

Folders

A Folder is a discrete Item set which supports aggregate operations. Folders are always in scope of a single customer. Folder supports hierarchy. Folder can contain folders. Folder is a loosely defined logical container (currently it doesn't have any special rules, e.g. you can have two folders with same name under the same parent folder). A folder can share multiple parent folders. A change to a folder made by one app (e.g. iOS Photos) will get reflected in another app (e.g. Web Files).

Response codes

The client passed in the invalid Auth token. Client should refresh the token and then try again.

403

Forbidden.

404

Resource not found.

412

Precondition failed, if ETags do not match.

500

Servers are not working as expected. The request is probably valid but needs to be requested again later.

503

Service Unavailable.

Getting List of Folders

Returns list of all folder metadata with base metadata. The listing limit is 200 per page. Response includes nextToken which can be passed in as the startToken in the next request to get the next set of folders.

GET : /nodes?filters=kind:FOLDER

filters

optional

filters for request, see [filtering](#Filtering)

startToken

optional

nextToken from previous request for access more content, see pagination

Response codes

The client passed in the invalid Auth token. Client should refresh the token and then try again.

403

Forbidden.

404

Resource Not Found.

500

Servers are not working as expected. The request is probably valid but needs to be requested again later.

503

Service Unavailable.

Properties

Extra properties which client wants to add to a node. Properties will be grouped together by the owner application Id which created them. By default, all properties will be restricted to its owner and no one else can read/write/delete them. As of now, only 10 properties can be stored by each owner. This is how properties would look inside a Node:

Adding One Property

To add one property to the node. If the key already exists then it will be overwritten. If the total property count for this owner exceeded 10 it will throw 400 Error.
Calling application must have write access for this property on given owner.

PUT : /nodes/{id}/properties/{owner}/{key}

id

The node Id to which the properties needs to be added.

key

The key of the properties which needs to be added. Key should just contain alphanumeric and "_". Max length is 50 characters.

owner

The "owner" of property, should be the friendlyName of your registered app.

Sample HTTP Response Headers

Response codes

Invalid Key or number of restricted property exceeded 10. The message will state the reason.

401

The client passed in the invalid Auth token. Client should refresh the token and then try again.

403

Forbidden.

404

Resource not found.

500

Servers are not working as expected. The request is probably valid but needs to be requested again later.

503

Service Unavailable.

List Properties

Returns list of properties for the node. Only those properties which caller application has read access to will be returned. Application cannot list all of its properties for a given node, it can only list properties under specific owner.

GET : /nodes/{id}/properties/{owner}

id

The node Id to which the properties needs to be added.

owner

The "owner" of property, should be the friendlyName of your registered app

Returns

Map of key-value pairs in a response field called "data"

Sample Request

GET : [https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/kuVKiKs46qQsI88sOVJFyI/properties/CloudDrive](#)

In order to limit the amount of data to receive per call, client pass in below two query parameter.

startToken

from where the next listing will start, All the listing API will return the nextToken in the response.

limit

maximum number of records to be returned. The default varies per list API. Refer individual API for its limit.

Current behavior is nextToken will be returned even if they are fewer elements than requested. The clients can use this nextToken and if they get no elements from the service, it means there are no elements.

Listing API support filtering based on node properties. Multiple filters can be specified using AND between filters. Currently only AND is supported.

filter

"property1:value1 AND property2:value2" or "property1:(value1* OR value2*) AND property3:(value3 AND value4)"

Fields

FieldName

FieldType

Sort Allowed

Notes

isRoot

Boolean

No

Only lower case "true" is supported.

name

String

Yes

This field does an exact match on the name and prefix query. Consider
node1{ "name" : "sample" }node2 { "name" : "sample1" }
Query filter
name:sample will return node1
name:sample* will return node1 and node2

kind

String

Yes

To search for all the nodes which contains kind as FILE kind:FILE

modifiedDate

Date (in ISO8601 Format)

Yes

To Search for all the nodes which has modified from time modifiedDate:{"2014-12-31T23:59:59.000Z" TO *]

createdDate

Date (in ISO8601 Format)

Yes

To Search for all the nodes created on createdDate:2014-12-31T23:59:59.000Z

labels

String Array

No

Only Equality can be tested with arrays.
if labels contains ["name", "test", "sample"].
Label can be searched for name or combination of values.
To get all the labels which contain name and testlabels: (name AND test)

description

String

No

To Search all the nodes for description with value 'test'description:test

parents

String Array

No

Only Equality can be tested with arrays.
if parents contains ["id1", "id2", "id3"].
Parent can be searched for name or combination of values.
To get all the parents which contains id1 and id2parents:id1 AND parents:id2

status

String

Yes

For searching nodes with AVAILABLE status.status:AVAILABLE

contentProperties.size

Long

Yes

contentProperties.contentType

String

Yes

If prefix query, only the major content-type (e.g. image*, video*, etc.) is supported as a prefix.

Example

If name contains a space, space should be escaped. For name = "Test 123":

https://drive.amazonaws.com/drive/v1/nodes?filters=name:Test\ 123

ETag

What is an ETag

Etag is essentially an identifier for a specific version of resource. By using Etags, we support conditional updates for most of the write operations (trash, purge, restore).

Where is ETag

In most read requests, Etag is returned as part of the response header; while in list requests, every node returned in a list request has its own "eTagResponse" field as part of the Metadata.

How to use ETag

Pass in ETag as If-Match header in the request, and the request will fail if the preconditions not met (node has been modified). It's also common to use ETag as changes identifier on client side - if ETag return is the same as last one, it means content wasn't changed and no updates needed.