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
Method | Http Request | Description |
---|---|---|
upload | POST : /nodes |
Upload a new file & its metadata |
overwrite | PUT : /nodes/{id}/content |
Overwrite the content of a file |
download | GET : /nodes/{id}/content |
Download a file with optional transformations |
tempLink | GET : |
Pre-authenticated download a file with optional transformations |
get | GET : /nodes/{id} |
Get a files metadata |
patch | PATCH : /nodes/{id} |
Partially update a files metadata |
list |
GET : /nodes?filters=kind:FILE
GET : /nodes?filters=kind:ASSET
|
Lists all the files/assets |
Folders
Method | Http Request | Description |
---|---|---|
create |
POST : /nodes
|
Creates a folder |
get |
GET : /nodes/{id}
|
Get a folder metadata |
patch |
PATCH : /nodes/{id}
|
Partially update a folder metadata |
list |
GET : /nodes?filters=kind:FOLDER
|
Lists all the folders |
Children
Method | Http Request | Description |
---|---|---|
add |
PUT : /nodes/{parentId}/children/{childId}
|
Adds child to a Folder |
move |
POST: /nodes/{toparentId}/children
|
Move a child from one node to another |
delete |
DELETE : /nodes/{parentId}/children/{childId}
|
Removes the child |
list |
GET : /nodes/{id}/children
|
Lists all children |
Properties
Method | Http Request | Description |
---|---|---|
add |
PUT : /nodes/{id}/properties/{owner}/{key}
|
Add a property |
get |
GET : /nodes/{id}/properties/{owner}/{key}
|
Get a property value |
list |
GET : /nodes/{id}/properties/{owner}
|
List all properties & values |
delete |
DELETE : /nodes/{id}/properties/{owner}/{key}
|
Delete a property |
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}
suppress |
optional | deduplication: disables checking for duplicates when uploading. |
Body Parameters
Multi-form part
Metadata
name |
required | file name. Max to 256 Characters. |
kind |
required | "FILE" |
labels |
optional | Extra information which is indexed. For example the value can be "PHOTO" |
properties |
optional | List of properties to be added for the file. |
parents |
optional | List of parent Ids. If no parent folders are provided, the file will be placed in the default root folder. |
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
Code | Description |
---|---|
201 | Created. |
400 | Bad input parameter. Error message should indicate which one and why. |
401 | The client passed in the invalid Auth token. Client should refresh the token and then try again. |
403 | Forbidden. |
409 | Duplicate file exists. |
500 | Servers are not working as expected. The request is probably valid but needs to be requested again later. |
503 | Service Unavailable. |
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
Code | Description |
---|---|
200 | OK. |
400 | Bad input parameter. Error message should indicate which one and why. |
401 | The client passed in the invalid Auth token. Client should refresh the token and then try again. |
403 | Forbidden. |
409 | Duplicate file exists. |
500 | Servers are not working as expected. The request is probably valid but needs to be requested again later. |
503 | Service Unavailable. |
Getting File Metadata
Retrieve the file Metadata by Id.
GET : /nodes/{id}?asset={assetMapping}&tempLink={true|false}
id |
required | Id of the file. |
assetMapping |
optional | default NONE, see [assetMapping](#AssetMapping) section |
tempLink |
optional | default to false, set true to include tempLink using which one can download content without authentication. |
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
Code | Description |
---|---|
200 | OK. |
400 | Bad input parameter. Error message should indicate which one and why. |
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. |
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
Code | Description |
---|---|
200 | OK. |
400 | Bad input parameter. Error message should indicate which one and why. |
401 | 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. |
Returns
List of file metadata.
count
- total number of nodes in all pagesnextToken
- 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
Code | Description |
---|---|
200 | OK. |
400 | Bad input parameter. Error message should indicate which one and why. |
401 | The client passed in the invalid Auth token. Client should refresh the token and then try again. |
403 | Forbidden. |
500 | Servers are not working as expected. The request is probably valid but needs to be requested again later. |
503 | Service Unavailable. |
Download File Content
Downloads the file.
GET : /nodes/{id}/content
id |
required | The ID of the file to be downloaded. |
viewBox |
optional | The size of image returned |
download |
optional | If true, the `content-disposition header` will contain "attachment". `response-content-disposition` overrides this value. It defaults to false. |
response-content-type |
optional | If specified, the content-type header of the response will be set to this value |
response-content-disposition |
optional | If specified, the content-disposition of the response will be set to this value. |
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
Code | Description |
---|---|
200 | OK. |
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. |
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}
localId |
required | Globally unique client local Id for the customer. The Id should be URL encoded. Max 100 characters. |
Body Parameters
name |
required | folder name. Max to 256 Characters. |
kind |
required | "FOLDER" |
labels |
optional | Extra information which is indexed. For example the value can be "SpringBreak" |
properties |
optional | List of properties to be added for the folder. |
parents |
optional | List of parent Ids. If no parent folders are provided, the folder will be placed in the default root folder. |
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
Code | Description |
---|---|
201 | Folder was created. |
400 | Bad input parameter. Error message should indicate which one and why. |
401 | The client passed in the invalid Auth token. Client should refresh the token and then try again. |
403 | Forbidden. |
409 | Conflict in case the ID was already used. |
500 | Servers are not working as expected. The request is probably valid but needs to be requested again later. |
503 | Service Unavailable. |
Getting Folder Metadata
Retrieve folder metadata by Id.
GET : /nodes/{id}
id |
Id of the folder. |
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
Code | Description |
---|---|
200 | OK. |
400 | Bad input parameter. Error message should indicate which one and why. |
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. |
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
Code | Description |
---|---|
200 | OK. |
400 | Bad input parameter. Error message should indicate which one and why. |
401 | 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 |
Returns
List of Folder metadata.
count |
total number of nodes in all pages | |
nextToken |
pagination token, see [pagination](#Pagination) |
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
Code | Description |
---|---|
200 | OK. |
400 | Bad input parameter. Error message should indicate which one and why. |
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. |
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
Code | Description |
---|---|
200 | OK. |
400 | Bad input parameter. Error message should indicate which one and why. |
401 | The client passed in the invalid Auth token. Client should refresh the token and then try again. |
403 | Forbidden. |
404 | Resource not found. |
409 | Duplicate Name conflict. |
500 | Servers are not working as expected. The request is probably valid but needs to be requested again later. |
503 | Service Unavailable. |
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
fromParent |
required | existing parent id. |
childId |
required | childId to be moved to another parent |
Response codes
Code | Description |
---|---|
200 | OK. |
401 | The client passed in the invalid Auth token. Client should refresh the token and then try again. |
403 | Forbidden. |
404 | Resource not found. |
409 | Duplicate Name conflict. |
500 | Servers are not working as expected. The request is probably valid but needs to be requested again later. |
503 | Service Unavailable. |
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
Code | Description |
---|---|
202 | Accepted. |
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 children
List all children of a node. List limit of 200.
GET : /nodes/{id}/children
id |
The unique identifier for a node whose children needs to be listed. | |
filters |
Optional | filters for request, see [filtering](#Filtering). |
startToken |
Optional | nextToken from previous request for access more content, see pagination. |
Returns
List of children metadata.
count |
total number of nodes in all pages. | |
nextToken |
pagination token, see [pagination](#Pagination) |
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
Code | Description |
---|---|
200 | OK. |
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. |
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}
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. |
Body Parameters
value |
required | The value of the property. Max length 500 characters. |
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
Code | Description |
---|---|
201 | Created. |
400 | 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](#)
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
Code | Description |
---|---|
200 | OK. |
400 | Bad input parameter. Error message should indicate which one and why. |
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. |
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}
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 |
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
Code | Description |
---|---|
200 | OK. |
401 | The client passed in the invalid Auth token. Client should refresh the token and then try again. |
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. |
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
Code | Description |
---|---|
204 | No Content. |
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. |
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.
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.
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.
sort |
This is of the format ["property1 ASC","property2 DESC", "property3"] |
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
-
Number of sort fields allowed - 2
-
Sortable fields -
createdDate
,modifiedDate
,contentDate
,name
,size
andcontentType
.
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.
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 filtername: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 test labels: (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 id2 parents: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. |
contentProperties.md5 | String | No | |
contentProperties.contentDate | Date (in ISO8601 Format) | Yes | RangeQueries and equals queries can be used with this field |
contentProperties.extension | String | Yes |
Restrictions
-
Num of filter parameters allowed - 8
-
Equality filters -
name
,status
,labels
,createdDate
,modifiedDate
,description
,parentIds
,isRoot
,kind
-
Range Filters -
modifiedDate
,createdDate
,contentProperties.contentDate
-
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.
Operation | Syntax |
---|---|
GreaterThan | {"valueToBeTested" TO *} |
GreaterThan or Equal | ["ValueToBeTested" TO *} |
LessThan | {* TO "ValueToBeTested"} |
LessThan or Equal | {* TO "ValueToBeTested"] |
Between | ["ValueToBeTested_LowerBound" TO "ValueToBeTested_UpperBound"] |
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
AssetMapping | Description |
---|---|
NONE | No assets will be returned for the given node. |
ALL | All assets will be returned for the given node. |
Support
If you have any questions, see the Developer Forum.