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.

Files

Folders

Children

Properties

Files

Files are binary bits stored in Amazon Drive along with its metadata.

Resource Model

{

"id" : {string} "unique identifier of a file", # string, max 50 characters
"name" : {string} "user friendly name of a file", # string, max 256 characters
"kind" : "FILE", # literal string, "FILE"
"version" : {long} metadata version of the file,
"modifiedDate" :  {datetime} Last modified date (ISO8601 date with timezone offset),
"createdDate" : {datetime} First uploaded date (ISO8601 date with timezone offset),
"labels" :  {string, string,...} List of Strings that are labeled to the file. Each label Max 256 characters. Max 10 labels.
"description" : {string} short description of the file. Max 500 characters.
"createdBy" : {string} Friendly name of Application Id which created the file (string),
"parents" : {String...} List of parent folder Ids.
"status" : {string} either "AVAILABLE", "TRASH", "PURGED" (string)
"tempLink" : {string} Pre authenticated link enables viewing the file content for limited times only; has to be specifically requested
}

{

"contentProperties" : {

"version" : {long} content version of the file (number),
"md5" : {string} md5 of a file content in HEX representation. (string),
"size" : {long} byte size (number, positive integer),
"contentType" : {string} Media Type defined as per RFC 2046 (string),
"extension" : {string} file extension (not including the '.') (string),
"contentDate" : {datetime} date extracted from media types (images and videos) (ISO8601 date with timezone offset), # over-writable

"image" : {

"height" : 1080,
"width" : 1620,
"make" : "Canon",
"model" : "Canon 550D",
"iso" :"200",
"exposureTime" : "1/320",
"aperture" : "4",
"dateTimeOriginal" : "2012-09-23T14:16:44.000Z",
"flash" : "Off",
"focalLength" : "200",
"dateTime" : "2012-09-25T22:39:32.000Z",
"dateTimeDigitized" : "2012-09-23T14:16:44.000Z",
"software" : "",
"orientation" : "1",
"colorSpace" : "sRGB",
"meteringMode" : "Partial",
"exposureProgram" : "Program Normal",
"exposureMode" : "Auto Exposure",
"sharpness" : "Unknown",
"whiteBalance" : "Auto",
"sensingMethod" : "One-chip color area",
"xresolution" : "72",
"yresolution" : "72",
"resolutionUnit" : "Pixels/Inch",
"gpsTimeStamp" : "20:16:40.123456789",
"location" : "+47.6235-122.3372+032.555/",
},


"video" :

// Properties for all videos:
"height" : 1080,
"width" : 1920,

// Additional properties for all videos other than migrated transcoded assets:
"createdDate" : "2014-03-31T17:12:10Z",
"duration" : "10.263220",
"videoCodec" : "h264",
"videoBitrate" : 13388331,
"videoFrameRate" : 29.97003,
"audioCodec" : "aac",
"audioBitrate" : 63219,
"audioSampleRate" : 44100,

// Additional properties for videos (and their assets), for new videos uploaded to Amazon Drive:
"audioChannels" : 1,
"audioChannelLayout" : "mono",
"bitrate" : 13434190,
"rotate" : "90",
"location" : "+47.6235-122.3372+032.555/",
"title" : "Cake fest 2000!",
"make" : "Apple",
"model" : "iPhone 5",
"encoder" : "7.1",
},


"properties" : {

"owner_app_id1" : { "key":"value", "key":"value", ...}
"owner_app_id2" : { "key":"value", "key":"value", ...},
"owner_app_id3" : { "key":"value", "key":"value", ...}

"assets" : [

# Inline list of assets nodes

]
}

Upload File

Uploads the file content along with its metadata information.

POST : /nodes?suppress={suppress}

Body Parameters

Multi-form part

Metadata

Content

File Bytes

Sample Request

POST /cdproxy/nodes?localId=testPhoto
HTTP/1.1
Host: content-na.drive.amazonaws.com
Authorization: Bearer
Atza|IQEBLjAsAhReYeezFcFdYzqrFOJGv3EG

----WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="metadata"

{"name":"fooo.jpg","kind":"FILE"}
----WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="content";
filename="db5df4870e4e4b6cbf42727fd434701a.jpg"
Content-Type: image/jpeg

----WebKitFormBoundaryE19zNvXGzXaLvS5C

cURL Request

curl -v -X POST --form
'metadata={"name":"testVideo1","kind":"FILE"}' --form
'content=@sample_iTunes.mp4'
'https://content-na.drive.amazonaws.com/cdproxy/nodes?localId=testVideo1&suppress=deduplication'
--header "Authorization: Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM"

Sample JSON Response

HTTP /1.1 201 Created location : "https://content-na.drive.amazonaws.com/cdproxy/nodes/eRkZ6YMuX5W3VqV3Ia7_lf
ETag : "efoDc0jSnpc"

{
"id" : "eRkZ6YMuX5W3VqV3Ia7_lf"
"name" : "fooo.jpg"
"kind" : "FILE",
"version" : 1,
"modifiedDate" : "2014-03-07T22:31:12.173Z",
"createdDate" : "2014-03-07T22:31:12.173Z",
"labels" : ["PHOTO"]
"description" : "My Awesome Photo".
"createdBy" : "ApplicationId1",
"parents" : ["foo1,"123"],
"status" : "Available"
"restricted" : false
"contentProperties" : {
"size" : 56654,
"version" : 1,
"contentType" : "image/jpeg",
"md5" : "6df23dc03f9b54cc38a0fc1483df6e21",
"extension" : "jpg",
"contentDate" : "2012-02-16T17:03:49.000Z",
"image" : {
"make": "SAMSUNG",
"model": "SAMSUNG-SGH-I747",
"exposureTime": "1/1780",
"dateTimeOriginal": "2012-08-25T14:23:24.000Z",
"flash": "No",
"focalLength": "37/10",
"dateTime": "2012-08-25T14:23:24.000Z",
"dateTimeDigitized": "2012-08-25T14:23:24.000Z",
"software": "I747UCALG1",
"orientation": "1",
"colorSpace": "sRGB",
"meteringMode": "CenterWeightedAverage",
"exposureProgram": "Aperture Priority",
"exposureMode": "Auto Exposure",
"whiteBalance": "Auto",
"sensingMethod": "One-chip color area",
"xResolution": "72",
"yResolution": "72",
"resolutionUnit": "Pixels/Inch",
"width": 220,
"height": 250
}
}
}

Response codes

Overwrite File

Overwrite the file content only.

PUT : /nodes/{id}/content

Body Parameters

Multi-form part

Content

File Bytes

Sample Request

PUT /cdproxy/nodes/CakUGFAiS5Gbs5Nozs1LRw/content HTTP/1.1
Host: content-na.drive.amazonaws.com
Authorization: Bearer
Atza|IQEBLjAsAhReYeezFcFdYzqrFOJGv3EG

----WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="content";
filename="db5df4870e4e4b6cbf42727fd434701a.jpg"
Content-Type: image/jpeg

----WebKitFormBoundaryE19zNvXGzXaLvS5C

cURL Request

curl -v -X PUT  --form 'content=@sample_iTunes.mp4'
'https://content-na.drive.amazonaws.com/cdproxy/nodes/CakUGFAiS5Gbs5Nozs1LRw/content'
--header "Authorization: Bearer Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM"

Sample JSON Response

HTTP /1.1 200

{
"id" : "eRkZ6YMuX5W3VqV3Ia7_lf"
"name" : "fooo.jpg"
"kind" : "FILE",
"version" : 1,
"modifiedDate" : "2014-03-07T22:31:12.173Z",
"createdDate" : "2014-03-07T22:31:12.173Z",
"labels" : ["PHOTO"]
"description" : "My Awesome Photo".
"createdBy" : "ApplicationId1",
"parents" : ["foo1,"123"],
"status" : "Available"
"restricted" : false
"contentProperties" : {
"size" : 56654,
"version" : 1,
"contentType" : "image/jpeg",
"md5" : "6df23dc03f9b54cc38a0fc1483df6e21",
"extension" : "jpg",
"contentDate" : "2012-02-16T17:03:49.000Z",
"image" : {
"make": "SAMSUNG",
"model": "SAMSUNG-SGH-I747",
"exposureTime": "1/1780",
"dateTimeOriginal": "2012-08-25T14:23:24.000Z",
"flash": "No",
"focalLength": "37/10",
"dateTime": "2012-08-25T14:23:24.000Z",
"dateTimeDigitized": "2012-08-25T14:23:24.000Z",
"software": "I747UCALG1",
"orientation": "1",
"colorSpace": "sRGB",
"meteringMode": "CenterWeightedAverage",
"exposureProgram": "Aperture Priority",
"exposureMode": "Auto Exposure",
"whiteBalance": "Auto",
"sensingMethod": "One-chip color area",
"xResolution": "72",
"yResolution": "72",
"resolutionUnit": "Pixels/Inch",
"width": 220,
"height": 250
}
}
}

Response codes

Getting File Metadata

Retrieve the file Metadata by Id.

GET : /nodes/{id}?asset={assetMapping}&tempLink={true|false}

Returns

The file base metadata.

Sample Request

GET /drive/v1/nodes/-ADSR01mQIKYMeXIKFK8JA?tempLink=true
HTTP/1.1
Host: drive.amazonaws.com
Authorization: Bearer
Atza|IQEBLjAsAhQnS5c3b6hzrBHBgJFUHKhDfvMO6wIUWL7JaM

cURL Request

curl -v
"https://drive.amazonaws.com/drive/v1/nodes/11jqgRBmPBKzlY6_bu9Pew?asset=ALL&tempLink=true"
--header "Authorization: Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM"

Sample JSON Response

HTTP /1.1 200 OK
ETag: "efoDc0jSnpc"

{
"id" : "eRkZ6YMuX5W3VqV3Ia7_lf"
"name" : "fooo.jpg"
"kind" : "FILE",
"version" : 1,
"modifiedDate" : "2014-03-07T22:31:12.173Z",
"createdDate" : "2014-03-07T22:31:12.173Z",
"labels" : ["PHOTO"]
"description" : "My Awesome Photo".
"createdBy" : "ApplicationId1",
"parents" : ["foo1","123"],
"status" : "Available",
"contentProperties" : {
"restricted" : false
"size" : 56654,
"version" : 1,
"contentType" : "image/jpeg",
"md5" : "6df23dc03f9b54cc38a0fc1483df6e21",
"extension" : "jpg",
"contentDate" : "2012-02-16T17:03:49.000Z",
"image" : {
"make": "SAMSUNG",
"model": "SAMSUNG-SGH-I747",
"exposureTime": "1/1780",
"dateTimeOriginal": "2012-08-25T14:23:24.000Z",
"flash": "No",
"focalLength": "37/10",
"dateTime": "2012-08-25T14:23:24.000Z",
"dateTimeDigitized": "2012-08-25T14:23:24.000Z",
"software": "I747UCALG1",
"orientation": "1",
"colorSpace": "sRGB",
"meteringMode": "CenterWeightedAverage",
"exposureProgram": "Aperture Priority",
"exposureMode": "Auto Exposure",
"whiteBalance": "Auto",
"sensingMethod": "One-chip color area",
"xResolution": "72",
"yResolution": "72",
"resolutionUnit": "Pixels/Inch",
},
},
"tempLink" : "http://s3-temp/fooo.jpg",
"properties" :{
"my_app_id" : {"key":"value", "key2","value2"}
}
}

Response codes

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.

PATCH : /nodes/{id}

Returns

File base Metadata.

Sample Request

PATCH : [https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/fooo](#) { "name" : "fooNew.jpg" }

cURL Request

curl -v -X PATCH --data '{"description": "a test file",
"name":"fooNew.jpg", "labels":["PHOTO", "test"]}'
https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/11jqgRBmPBKzlY6_bu9Pew
--header 'Authorization: Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM'

Sample JSON Response

HTTP /1.1 200 OK
ETag: "efoDc0jSnpc"

{
"id" : "eRkZ6YMuX5W3VqV3Ia7_lf"
"name" : "fooNew.jpg"
"kind" : "FILE",
"version" : 1,
"modifiedDate" : "2014-03-07T22:31:12.173Z",
"createdDate" : "2014-03-07T22:31:12.173Z",
"labels" : ["PHOTO"]
"description" : "My Awesome Photo".
"createdBy" : "ApplicationId1",
"parents" : ["foo1","123"],
"status" : "Available",
"restricted" : false
"contentProperties" : {
"size" : 56654,
"version" : 1,
"contentType" : "image/jpeg",
"md5" : "6df23dc03f9b54cc38a0fc1483df6e21",
"extension" : "jpg",
"contentDate" : "2012-02-16T17:03:49.000Z",
"image" : {
"make": "SAMSUNG",
"model": "SAMSUNG-SGH-I747",
"exposureTime": "1/1780",
"dateTimeOriginal": "2012-08-25T14:23:24.000Z",
"flash": "No",
"focalLength": "37/10",
"dateTime": "2012-08-25T14:23:24.000Z",
"dateTimeDigitized": "2012-08-25T14:23:24.000Z",
"software": "I747UCALG1",
"orientation": "1",
"colorSpace": "sRGB",
"meteringMode": "CenterWeightedAverage",
"exposureProgram": "Aperture Priority",
"exposureMode": "Auto Exposure",
"whiteBalance": "Auto",
"sensingMethod": "One-chip color area",
"xResolution": "72",
"yResolution": "72",
"resolutionUnit": "Pixels/Inch",
},
},
"properties" :{
"my_app_id" : {"key":"value", "key2","value2"}
}
}

Response codes

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

Returns

List of file metadata.

• count - total number of nodes in all pages
• nextToken - pagination token, see pagination

Sample Request

GET : [https://cdws.us-east-1.amazonaws.com/drive/v1/nodes?filters=kind:FILE](#)

cURL Request

curl -v
    "https://cdws.us-east-1.amazonaws.com/drive/v1/nodes?filters=kind:FILE"
    --header "Authorization: Bearer
    Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM"

Sample JSON Response

HTTP /1.1 200 OK
{
"count" : 1000,
"nextToken" : "kgkbpodpt6",

"data": [

{
"eTagResponse":"eodh1-sfNbMI",
"id":"eRkZ6YMuX5W3VqV3Ia7_lf",
"name":"fooNew.jpg",
"kind":"FILE",
"metadataVersion":1,
"modifiedDate":"2014-03-07T22:31:12.173Z",
"createdDate":"2014-03-07T22:31:12.173Z",
"labels":["PHOTO"],
"description":"My Awesome Photo",
"createdBy":"ApplicationId1",
"parents":["foo1","123"],
"status":"Available",
"restricted":false,
"size":56654,
"contentType":"image/jpeg",
"md5":"6df23dc03f9b54cc38a0fc1483df6e21",
"fileExtension":"jpeg",
"contentProperties":{
"image":{
"make":"SAMSUNG",
"model":"SAMSUNG-SGH-I747",
"exposureTime":"1/1780",
"dateTimeOriginal":"2012-08-25T14:23:24.000Z",
"flash":"No",
"focalLength":"37/10",
"dateTime":"2012-08-25T14:23:24.000Z",
"dateTimeDigitized":"2012-08-25T14:23:24.000Z",
"software":"I747UCALG1",
"orientation":"1",
"colorSpace":"sRGB",
"meteringMode":"CenterWeightedAverage",
"exposureProgram":"Aperture Priority",
"exposureMode":"Auto Exposure",
"whiteBalance":"Auto",
"sensingMethod":"One-chip color area",
"xResolution":"72",
"yResolution":"72",
"resolutionUnit":"Pixels/Inch"
}
}
},
{
"eTagResponse":"sdgrrtbbfdd",
"id":"fooo1",
"name":"foo.zip",
"kind":"FILE",
"metadataVersion":1,
"modifiedDate":"2014-03-07T22:31:12.173Z",
"createdDate":"2014-03-07T22:31:12.173Z",
"labels":["ZIP File"],
"description":"All My Data",
"createdBy":"ApplicationId2",
"status":"Available",
"restricted":false,
"size":5665423,
"contentType":"application/octet-stream",
"md5":"6df23dc03f9b54cc38a0fc1483df6e23",
"fileExtension":"zip"
}...
]

Response codes

Download File Content

Downloads the file.

GET : /nodes/{id}/content

Returns

Returns the content in the response body.

Sample Request

GET : [https://content-na.drive.amazonaws.com/cdproxy/nodes/{id}/content](#)

cURL Request

curl -v
https://content-na.drive.amazonaws.com/cdproxy/v1/nodes/0mW4UdUaNj6wLG7G2YCCVg/content
--header "Authorization: Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM"

Sample HTTP Response Headers

HTTP/1.1 200 OK
data: { file-content }

Response codes

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.

Resource Model

{
"id" : {string} "unique identifier of a file", # string, max 50 characters
"name" : {string} "user friendly name of a file", # string, max 256 characters
"kind" : "FILE", # literal string, "FILE"
"version" : {long} metadata version of the file,
"modifiedDate" : {datetime} Last modified date (ISO8601 date with timezone offset),
"createdDate" : {datetime} First uploaded date (ISO8601 date with timezone offset),
"labels" : {string, string,...} List of Strings that are labeled to the file. Each label Max 256 characters. Max 10 labels.
"description" : {string} short description of the file. Max 500 characters.
"createdBy" : {string} Friendly name of Application Id which created the file (string),
"parents" : {String...} List of parent folder Ids.
"status" : {string} either "AVAILABLE", "TRASH", "PURGED" (string)
"tempLink" : {string} Pre authenticated link enables viewing the file content for limited times only; has to be specifically requested
}

{

"contentProperties" : {

"version" : {long} content version of the file (number),
"md5" : {string} md5 of a file content in HEX representation. (string),
"size" : {long} byte size (number, positive integer),
"contentType" : {string} Media Type defined as per RFC 2046 (string),
"extension" : {string} file extension (not including the '.') (string),
"contentDate" : {datetime} date extracted from media types (images and videos) (ISO8601 date with timezone offset), # over-writable

"image" : {

"height" : 1080,
"width" : 1620,
"make" : "Canon",
"model" : "Canon 550D",
"iso" : "200",
"exposureTime" : "1/320",
"aperture" : "4",
"dateTimeOriginal" : "2012-09-23T14:16:44.000Z",
"flash" : "Off",
"focalLength" : "200",
"dateTime" : "2012-09-25T22:39:32.000Z",
"dateTimeDigitized" : "2012-09-23T14:16:44.000Z",
"software" : "",
"orientation" : "1",
"colorSpace" : "sRGB",
"meteringMode" : "Partial",
"exposureProgram" : "Program Normal",
"exposureMode" : "Auto Exposure",
"sharpness" : "Unknown",
"whiteBalance" : "Auto",
"sensingMethod" : "One-chip color area",
"xresolution" : "72",
"yresolution" : "72",
"resolutionUnit" : "Pixels/Inch",
"gpsTimeStamp" : "20:16:40.123456789",
"location" : "+47.6235-122.3372+032.555/",
},

"video" : {
// Properties for all videos:

"height" : 1080,
"width" : 1920,

// Additional properties for all videos other than migrated transcoded assets:

"createdDate" : "2014-03-31T17:12:10Z",
"duration" : "10.263220",
"videoCodec" : "h264",
"videoBitrate" : 13388331,
"videoFrameRate" : 29.97003,
"audioCodec" : "aac",
"audioBitrate" : 63219,
"audioSampleRate" : 44100,

// Additional properties for videos (and their assets), for new videos uploaded to Amazon Drive:

"audioChannels" : 1,
"audioChannelLayout" : "mono",
"bitrate" : 13434190,
"rotate" : "90",
"location" : "+47.6235-122.3372+032.555/",
"title" : "Cake fest 2000!",
"make" : "Apple",
"model" : "iPhone 5",
"encoder" : "7.1",
},

"properties" : {

"owner_app_id1" : { "key":"value", "key":"value", ...}
"owner_app_id2" : { "key":"value", "key":"value", ...},
"owner_app_id3" : { "key":"value", "key":"value", ...}
}

}

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).

Resource Model

{

"id" : {String} unique identifier of a folder. Max 22 characters (String)  
"name" : {String} user friendly name of a folder. Max 256 characters (String)  
"kind" : "FOLDER",  
"version" : {long} metadata version of the folder(Number),  
"modifiedDate" : {dateTime} Last modified date (dateTime),  
"createdDate" : {dateTime} First creation date(dateTime),  
"labels" : {String...} List of Strings that are labeled to the folder. Each label Max 256 characters.  
"description" : {String} short description of the folder. Max 500 characters.  
"createdBy" : {String} Application Id which created the folder (String),  
"parents" : {String...} List of Id's of folder who are parent of this. (List<String>)  
"status" : {String} either "AVAILABLE", "TRASH", "PURGED" (String)  
"restricted" : {boolean} indicates whether the file is restricted to that app only or accessible to all the applications. (boolean)  
"isRoot" : {boolean} indicates whether the folder is a root folder or not.  
"isShared" : {boolean} set if node is shared

"properties" : {  
"owner_app_id1" : {"key":"value", "key2","value2"},  
"owner_app_id2" : {"foo":"bar"},  
"owner_app_id3": {"foo": "true"},  
}  
}

Create Folder

Creates a new Folder for a customer.

POST : /nodes?localId={localId}

Body Parameters

Returns

The Folder Base metadata.

Sample Request

POST : https://drive.amazonaws.com/drive/v1/nodes { "name" : "CameraRoll", "labels" : ["SpringBreak"], "parents" : ["foo1","123"], "properties" : { "my_app_id" : {"key":"value", "key2","value2"} } "kind" : "FOLDER" }

cURL Request

curl -v -X POST --data '{"name":"CameraRoll2", "kind":"FOLDER",
"labels":["SpringBreak"]}'
https://drive.amazonaws.com/drive/v1/nodes --header
"Authorization: Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM"

Sample JSON Response

location : "https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/oBtPyMPRFGlw6WLZVSCeAd
HTTP /1.1 201 Created
ETag : "xNTvQE8OiRo"

{
"id" : "oBtPyMPRFGlw6WLZVSCeAd"
"name" : "CameraRoll"
"kind" : "FOLDER",
"version" : 1,
"modifiedDate" : "2014-03-07T22:31:12.173Z",
"createdDate" : "2014-03-07T22:31:12.173Z",
"labels" : ["ALBUM"],
"createdBy" : "ApplicationId1",
"parents" : ["foo1","123"],
"status" : "AVAILABLE",
"restricted" : false
}

Response codes

Getting Folder Metadata

Retrieve folder metadata by Id.

GET : /nodes/{id}

Returns

The folder base metadata.

Sample Request

GET : [https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/oBtPyMPRFGlw6WLZVSCeAd?fields=["properties"]](#)

cURL Request

curl -v
https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/iv2VPgooQOa7ggf4jLFikA
--header "Authorization: Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM"

Sample JSON Response:

HTTP /1.1 200 OK
ETag : "xNTvQE8OiRo"

{
"id" : "oBtPyMPRFGlw6WLZVSCeAd"
"name" : "CameraRoll"
"kind" : "FOLDER",
"version" : 1,
"modifiedDate" : "2014-03-07T22:31:12.173Z",
"createdDate" : "2014-03-07T22:31:12.173Z",
"labels" : ["ALBUM"],
"createdBy" : "ApplicationId1",
"parents" : ["foo1","123"],
"status" : "AVAILABLE",
"restricted" : false,

"properties" : {
"my_app_id" : {"key":"value", "key2","value2"}
}
}

Response codes

Partial Update Folder Metadata

To update partial folder 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 update are name, labels, description.

PATCH : /nodes/{id}

Returns

Folder base Metadata.

Sample Request:

PATCH : [https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/oBtPyMPRFGlw6WLZVSCeAd](#)

{ "name" : "Camera" }

cURL Request

curl -v -X PATCH --data '{"name":"Camera"}'
https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/iv2VPgooQOa7ggf4jLFikA
--header 'Authorization: Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM'

Sample JSON Response:

HTTP /1.1 200 OK
ETag : "xNTvQE8OiRo"

{
"id" : "oBtPyMPRFGlw6WLZVSCeAd"
"name" : "Camera"
"kind" : "FOLDER",
"version" : 1,
"modifiedDate" : "2014-03-07T22:31:12.173Z",
"createdDate" : "2014-03-07T22:31:12.173Z",
"labels" : ["ALBUM"],
"createdBy" : "ApplicationId1",
"parents" : ["foo1","123"],
"status" : "AVAILABLE",
"restricted" : false,

"properties" : {
"my_app_id" : {"key":"value", "key2","value2"}
}
}

Response codes

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

Returns

List of Folder metadata.

cURL Request:

curl -v
"https://cdws.us-east-1.amazonaws.com/drive/v1/nodes?filters=kind:FOLDER"
--header "Authorization: Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM"

Sample JSON Response

HTTP /1.1 200 OK

{
"count" : 2000,
"nextToken" : "1asdkelrewlrgerrtr",

"data":[
{
"eTagResponse" : "eodh1-sfNbMI",
"id" : "oBtPyMPRFGlw6WLZVSCeAd"
"name" : "Camera"
"kind" : "FOLDER",
"version" : 1,
"modifiedDate" : "2014-03-07T22:31:12.173Z",
"createdDate" : "2014-03-07T22:31:12.173Z",
"labels" : ["ALBUM"],
"createdBy" : "ApplicationId1",
"parents" : ["_5C93At1J4wB_FA5XWoesQ","TtprUeJnw3EXcn7H3E8lAz"],
"status" : "AVAILABLE",
"restricted" : false
},
{
"eTagResponse" : "rtbdwegefew",
"id" : "uPxN8K9kQwTmgdVhfcX5YR"
"name" : "Vacation"
"kind" : "FOLDER",
"version" : 1,
"modifiedDate" : "2014-03-07T22:31:12.173Z",
"createdDate" : "2014-03-07T22:31:12.173Z",
"labels" : ["Vacation"],
"createdBy" : "ApplicationId2",
"parents" : ["_5C93At1J4wB_FA5XWoesQ,"TtprUeJnw3EXcn7H3E8lAz"],
"status" : "AVIALABLE",
"restricted" : false
},...
]
}

Response codes

Children

Node can have children. The childId should be different from the parent id.

Add a Child

Add a file/folder to a folder.

PUT : /nodes/{parentId}/children/{childId}

Sample Request

PUT : [https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/xZ2ZJBmnDT_rJ8Zira9JXa/children/foo](#)

cURL Request

curl -v -X PUT
https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/161kKftTTTuRee1hicOhAw/children/0mW4UdUaNj6wLG7G2YCCVg
--header "Authorization:Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM" --header
'Content-Length: 0'

Sample JSON Response

HTTP /1.1 200 OK.

Response codes

Move a Child

Move a node from being a child of some node to being a child of a different node. This is currently limited to FILES and FOLDERS. Use add/remove child for other KINDS.

POST : /nodes/{toParentId}/children

Body Parameters

Response codes

Remove a Child Membership

Remove a node from child membership.

DELETE : /nodes/{parentId}/children/{childId}

Sample Request

DELETE : [https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/xZ2ZJBmnDT_rJ8Zira9JXa/children/foo](#)

cURL Request

curl -v -X DELETE
https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/161kKftTTTuRee1hicOhAw/children/0mW4UdUaNj6wLG7G2YCCVg
--header "Authorization:Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM"

Sample JSON Response

HTTP /1.1 202 Accepted.

Response codes

List children

List all children of a node. List limit of 200.

GET : /nodes/{id}/children

Returns

List of children metadata.

Sample Request:

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

cURL Request

curl -v
"https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/bCxmCQt_StWe4M6xA_Udng/children?limit=10&filters=kind:FOLDER"
--header "Authorization:Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM"

Sample JSON Response

HTTP /1.1 200 OK

{
"count" : 2000,
"nextToken" : "1asdkelrewlrgerrtr",

"data":[
{
"eTagResponse" : "eodh1-sfNbMI",
"id" : "oBtPyMPRFGlw6WLZVSCeAd"
"name" : "Camera"
"kind" : "FOLDER",
"version" : 1,
"modifiedDate" : "2014-03-07T22:31:12.173Z",
"createdDate" : "2014-03-07T22:31:12.173Z",
"labels" : ["ALBUM"],
"createdBy" : "ApplicationId1",
"parents" : ["_5C93At1J4wB_FA5XWoesQ","TtprUeJnw3EXcn7H3E8lAz"],
"status" : "AVAILABLE",
"restricted" : false
},
{
"eTagResponse" : "rtbdwegefew",
"id" : "uPxN8K9kQwTmgdVhfcX5YR"
"name" : "Vacation"
"kind" : "FOLDER",
"version" : 1,
"modifiedDate" : "2014-03-07T22:31:12.173Z",
"createdDate" : "2014-03-07T22:31:12.173Z",
"labels" : ["Vacation"],
"createdBy" : "ApplicationId2",
"parents" : ["_5C93At1J4wB_FA5XWoesQ,"TtprUeJnw3EXcn7H3E8lAz"],
"status" : "AVIALABLE",
"restricted" : false
},...
]
}

Response codes

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:

"properties": {

"owner_app_id1": { "key":"value", "key":"value", ...}  
"owner_app_id2": { "key":"value", "key":"value", ...},  
"owner_app_id3": { "key":"value", "key":"value", ...}  
}

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}

Body Parameters

Sample Request

PUT : [https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/kuVKiKs46qQsI88sOVJFyI/properties/CloudDrive/s3_storageKey](#)  
{  
"value" : "foobar"  
}

cURL Request:

curl -v -X PUT --data '{"value":"testValue1"}'
https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/bCxmCQt_StWe4M6xA_Udng/properties/CloudDrive/testKey1
--header "Authorization:Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM"

Sample HTTP Response Headers

HTTP/1.1 201 OK

{
"statusCode": 201,
"location":
"development.amazon.com/drive/v1/nodes/t21/properties/CloudDrive/s3_storageKey",
"value": "v1",
"key": "s3_storageKey"
}

Response codes

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}

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](#)

cURL Request

curl -v
https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/bCxmCQt_StWe4M6xA_Udng/properties/CloudDrive
--header "Authorization:Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM"

Sample JSON Response

HTTP /1.1 200 OK

{
"statusCode": 200,
"data": {
"s3_bucket": "p",
"s3_storageKey": "v1"
}
}

Response codes

Get Property Value

Returns the property value, with a given key and owner. Caller app must have read access to this property.

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

Returns

The node property key value pair

Sample Request

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

cURL Request

curl -v
https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/bCxmCQt_StWe4M6xA_Udng/properties/CloudDrive/testKey1
--header "Authorization:Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM"

Sample JSON Response

HTTP /1.1 200 OK
{
"statusCode": 200,
"value": "v1",
"key": "s3_storageKey"
}

Response codes

Delete Property

Permanently deletes the property. Caller app must have write access to this property.

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

Sample Request

DELETE : https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/kuVKiKs46qQsI88sOVJFyI/properties/CloudDrive/s3_storageKey

cURL Request

curl -v -X DELETE
https://cdws.us-east-1.amazonaws.com/drive/v1/nodes/bCxmCQt_StWe4M6xA_Udng/properties/CloudDrive/testKey1
--header "Authorization:Bearer
Atza|IQEBLjAsAhQ5zx7pKp9PCgCy6T1JkQjHHOEzpwIUQM"

Sample JSON Response

HTTP /1.1 204 No Content.

Response codes

Common Operations

Pagination

All the listing API will have pagination.

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

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.

Sorting

Sort is not allowed on parents and labels as they are list. All the listing API will have sorting. To sort the listing in order required by the client.

Suffix the sort property with a Sort Order (ASC/DESC) separated by space. If only sort property is mentioned with out the sort order, it is defaulted to Sort Order DESC.

Restrictions

1. Number of sort fields allowed - 2 

2. Sortable fields - createdDate, modifiedDate, contentDate, name, size and contentType.

Examples

To sort on name in ascending and size in contentProperties in descending, there are two ways to achieve this:

sort:["name ASC","contentProperties.size DESC"]

or

sort:["name ASC","contentProperties.size"]

Filtering

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

Fields

Restrictions

1. Num of filter parameters allowed - 8

2. Equality filters - name, status, labels, createdDate, modifiedDate, description,  parentIds, isRoot, kind

3. Range Filters - modifiedDate, createdDate, contentProperties.contentDate

4. Prefix Filters - name, contentProperties.contentType

Basic Examples

To get name that is equal to Test, the filter must be mentioned in this format: 

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

Prefix queries can be applied to name. To get name that starts With Test:

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

Prefix queries can also be applied to images and videos. To get contentType that starts With the image and video:

https://drive.amazonaws.com/drive/v1/nodes?filters=contentProperties.contentType:(image* OR video*)

Filter clauses can be combined with AND operator. To get all nodes with name Test and contentType starts With image and video:

https://drive.amazon.com/drive/v1/nodes?filters=name:Test AND contentProperties.contentType:(image* OR video*)

Booleans should be lowercase true/false. To get the root folder:

https://drive.amazon.com/drive/v1/nodes?filters=kind:FOLDER AND isRoot:true

Range Filters

Values for range queries must be "" (Double quotes) to work correctly.

Example

To add a filter for modifiedDate > "2014-12-31T23:59:59.000Z"

https://drive.amazonaws.com/drive/v1/nodes?filters=modifiedDate:{2014-12-31T23:59:59.000Z TO *}

To add a filter for modifiedDate <= "2014-12-31T23:59:59.000Z"

https://drive.amazonaws.com/drive/v1/nodes?filters=modifiedDate:{* TO 2014-12-31T23:59:59.000Z]

To add a filter for "2014-01-01T00:00:00.000Z" >= modifiedDate <= "2014-12-31T23:59:59.000Z"

https://drive.amazonaws.com/drive/v1/nodes?filters=modifiedDate:[2014-01-01T00:00:00.000Z TO 2014-12-31T23:59:59.000Z]

Escaping

Special characters that are part of the query syntax should be escaped. The list of special characters are:

• • & | ! ( ) { } [ ] ^ ' " ~ * ? : \
    Additionally, space should be escaped. To escape these characters, use \ before the character.

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.

cURL Request

PATCH /drive/v1/nodes/Ku3A1FfoPAG16iNWsoQKjQ HTTP/1.1
Host: cdws.us-east-1.amazonaws.com
Authorization: Bearer
Atza|IQEBLzAtAhUAj6aYu5ZpKHt_1Yjy11_ZKFJ
If-Match: SVgJfMhZvRY

Sample JSON Response

HTTP /1.1 412 Precondition Failed
{
"message": "ETag SVgJfMhZvRY do not match."
}

Asset Mapping

Support

If you have any questions, see the Developer Forum.