Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Panel
titleContent REST Methods

Get Content

  • Purpose: Retrieves a piece of content along with its properties
  • Request: GET https://host:port/durastore/spaceID/contentID ? (storeID) (attachment)
    • if attachment param value is true, a Content-Disposition header is included with the response
  • Request Headers: Range of bytes to retrieve from the file (optional) (Available in DuraCloud v5.0.0+)

    Code Block
    Range:bytes=byte_range


    • Value of Range header must begin with "bytes=" followed by the byte range

    • Only 1 byte range is supported per request, all ranges specified beyond the first are discarded

    • Examples of valid Range header values:
      • bytes=0-499 (retrieves the first 500 bytes from a file)
      • bytes=500-999 (retrieves the second 500 bytes from a file)
      • bytes=1000- (retrieves all bytes starting with 1000 to the end of the file)
  • Response Code:
    • 200 (on success, for a complete file)
    • 206 (on success, for a range-limited set of bytes in the file)
    • 400 (on invalid request, such as if a Range header includes an invalid value)
  • Response Body: The content stream
  • Response Headers: All available content properties, example:

    Code Block
    languagenone
    Content-Type: text/plain
    Content-Length: 5732
    Content-MD5: 3456709234785097473839202
    ETag: 3456709234785097473839202
    x-dura-meta-content-name: Testing Content
    x-dura-meta-content-owner: JSmith
    


Get Content Properties

  • Purpose: Retrieves the properties of a piece of content without the content itself
  • Request: HEAD https://host:port/durastore/spaceID/contentID ? (storeID)
  • Response Code: 200 (on success)
  • Response Headers: Same as Get content (above)

Store Content

  • Purpose: Adds a piece of content to the store
  • Request: PUT https://host:port/durastore/spaceID/contentID ? (storeID)
  • Request Body: Content to be added
  • Request Headers: Properties about the content, example:

    Code Block
    languagenone
    Content-Type: text/plain
    Content-MD5: 4cd56e137a93a1accb43c5d32f4afffb
    x-dura-meta-content-name: Testing Content
    x-dura-meta-content-owner: JSmith
    


  • Response Code:
    • 201 (on success)
    • 400 (if the content ID is invalid)
    • 404 (if the the given space does not exist)
    • 409 (if the provided checksum did not match the stored content checksum)
    • 500 (on error)
  • Response Headers:
    • MD5 checksum of stored content
    • ETag of stored content
    • Location of the new content (i.e. the URL used to create the content), example:

      Code Block
      languagebash
      Content-MD5: 4cd56e137a93a1accb43c5d32f4afffb
      ETag: 4cd56e137a93a1accb43c5d32f4afffb
      Location: https://myhost:8080/durastore/space1/content1
      


  • Usage Notes
    • When the optional Content-MD5 header is included, the final checksum of the stored file is compared against the MD5 value included in the header to ensure that the file was stored correctly. If the header is not included, an MD5 checksum is computed as the file is transferred to storage, and that value is used in the final comparison.
    • All properties to be set must be included as a request header with the prefix "x-dura-meta-". Any header using the "x-dura-meta-" prefix will be stored as a content property, with a few exceptions, which are used for specific other purposes:
      • Headers used as part of the Copy Content request

        Code Block
        x-dura-meta-copy-source
        x-dura-meta-copy-source-store


      • Headers used to provide details about a space (these cannot be set)

        Code Block
        x-dura-meta-space-count
        x-dura-meta-space-created


      • Headers used as part of the Set Space ACLs call (the * is replaced by the user or group name)

        Code Block
        x-dura-meta-acl-*
        x-dura-meta-acl-group-*


      • Headers used internal to DuraCloud

        Code Block
        x-dura-meta-content-mimetype (set Content-Type header instead)
        x-dura-meta-content-size (automatically written as Content-Length header)
        x-dura-meta-content-checksum (automatically written as Content-MD5 header)
        x-dura-meta-content-modified (automatically written as Last-Modified header)


      • Headers used by the DuraCloud SyncTool to automatically capture file details

        Code Block
        x-dura-meta-creator
        x-dura-meta-content-file-created
        x-dura-meta-content-file-modified
        x-dura-meta-content-file-last-accessed
        x-dura-meta-content-file-path


    • Use only US-ASCII characters for property names and values

    • There is a 2 KB total size limit on all content properties (this includes both auto-generated and user contributed properties.)

    • The "x-dura-meta-" prefix is case-sensitive (make sure your clients do not automatically change case.)

Copy Content

  • Purpose: Copies a piece of content from a source space to a destination space within a given store
  • Request: PUT https://host:port/durastore/spaceID/contentID ? (storeID)
  • Request Body: must not exist
  • Request Headers: Copy source, example:

    Code Block
    languagenone
    x-dura-meta-copy-source: space-id/content-id
    


  • Optional Request Headers: Copy source store, example:

    Code Block
    languagenone
    x-dura-meta-copy-source-store: storeId
    


  • Response Code: 201 (on success)
  • Response Headers:
    • MD5 checksum of stored content
    • ETag of stored content
    • Location of the new content (i.e. the URL used to create the content), example:

      Code Block
      languagebash
      Content-MD5: 4cd56e137a93a1accb43c5d32f4afffb
      ETag: 4cd56e137a93a1accb43c5d32f4afffb
      Location: https://myhost:8080/durastore/space1/content1
      


  • Usage Notes
    • The properties associated with the source content item are copied to the destination content item.
    • The source and destination spaces may be the same.
    • Including the optional header indicates that the copy action should retrieve the source file from a space in the specified storage provider. This allows for copying a file from one storage provider to another.

Set Content Properties

  • Purpose: Updates the properties associated with a piece of content. Note: You must include ALL properties you would like associated with the given content item in this call. Any properties that exist before this call but are not included in the call itself will be removed. This is to allow for both adding and removing properties.
  • Request: POST https://host:port/durastore/spaceID/contentID ? (storeID)
  • Request Headers: Same as Store content (above)
  • Response Code: 200 (on success)
  • Response Body: "Content $contentID updated successfully"

Delete Content

  • Purpose: Removes a piece of content from the store
  • Request: DELETE https://host:port/durastore/spaceID/contentID ? (storeID)
  • Response Code: 200 (on success)
  • Response Body: "Content $contentID deleted successfully"

...

Panel
titleAuxiliary REST Methods

Get Streaming Cookies

(Available in DuraCloud 5.0.0+)

  • Purpose: To be used in conjunction with secure HLS streaming in order to allow for setting access cookies on the user's browser. This endpoint is not called directly but is accessed by using the streaming distribution domain as a proxy, thus allowing cookies associated with that domain to be set. The response headers set the cookies. The body of the response is an HTML document which redirects the user. Expected to be used in combination with the get-signed-cookies-url S3 Task.
  • Request: GET https://host:port/durastore/aux/cookies ? (token)
    • token - Token generated when cookie data is stored
  • Response Code: 200 (on success), 404 if the specified token does not exisst

  • Response Headers: 3 Set-Cookie headers (CloudFront-Policy, CloudFront-Signature, CloudFront-Key-Pair-Id)

...

Panel
titleTask REST Methods


Info

Tasks are used to perform storage provider actions which cannot be performed in a generic manner across multiple providers.

Get Tasks

  • Purpose: Provides a listing of all of the supported tasks for a given provider. Note that if no storeID parameter is included, the task listing is provided for the primary storage provider.
  • Request: GET https://host:port/durastore/task ? (storeID)
  • Response Code: 200 (on success)
  • Response Body: XML similar to:

    Code Block
    languagehtml/xml
    <list>
      <string>task1</string>
      <string>task2</string>
    </list>
    


Perform Task

  • Purpose: Performs a particular task. Note that most tasks can be performed by only one storage provider type.
  • Request: POST https://host:port/durastore/task/taskName ? (storeID)
  • Request Body: Parameters for task. Each task will expect parameters in a specific format, see task listing for more details.
  • Response Code: 200 (on success)
  • Response Body: Response value for task, format varies by task.

Tasks

Amazon S3 Storage Provider
HTTP Live Streaming support
(Available in DuraCloud 5.0.0+)

taskName

Name

Description

Request Body

Response Body

enable-hls

Enable HLS Streaming task

Enables HTTP Live Streaming (HLS) for all files within a DuraCloud space through the use of Amazon's Cloudfront streaming capability. This task may take up to 15 minutes to complete.

When this call completes, two new properties will have been added to the set of properties for the specified space:

  • hls-streaming-host - this is the HLS host value, which can be used to generate URLs for streaming
  • hls-streaming-type - will either be OPEN or SECURE, depending on the value of the secure parameter provided when streaming was enabled


No Format
{
  "spaceId" : "",
  "secure" : "",
  "allowedOrigins" : ["",""]
}

spaceId - Name of the space for which streaming is to be enabled

secure - true or false, should streaming be secured

allowedOrigins - A list of allowed origins which limits the domains that may access the content in a streamed space under the CORS security model (optional, default is "https://*")


No Format
{
  "result" : "",
  "streamingHost" : ""
}

result - Text indicating the results of the task

streamingHost - The host name of the streaming endpoint

disable-hls

Disable HLS Streaming task

Disables streaming by removing the ability for Cloudfront to access files within a space. This does not remove the streaming distribution, only disables its use, so enabling streaming on the same space again can be performed much more quickly. Some content in the space may continue to be available for streaming up to 24 hours after streaming has been disabled.


No Format
{
  "spaceId" : ""
}

spaceId - Name of the space for which streaming is to be disabled


No Format
{
  "result" : ""
}

result - Text indicating the results of the task

delete-hls

Delete HLS Streaming task

Removes a streaming distribution created by the enable-streaming task. This task should be performed after performing the disable-streaming task. This task may take up to 15 minutes to complete, after which no content in the space will be available for streaming.

This task can be used to transition a space where streaming has been enabled from Open to Secure or Secure to Open.


No Format
{
  "spaceId" : ""
}

spaceId - Name of the space for which streaming is to be deleted


No Format
{
  "result" : ""
}

result - Text indicating the results of the task

get-url-hlsGet URL for HLS task

Retrieves a URL for a media file that is streamed through CloudFront via HLS


No Format
{
  "spaceId" : "",
  "contentId" : "",
}

spaceId - Name of the space in which the streamed content is stored

contentId - Name of the content item to be streamed 


No Format
{
  "streamUrl" : ""
}

streamUrl - The URL to be used for streaming the requested content

get-signed-cookies-urlGet Signed Cookies URL task

Generates a set of cookies to be set on the end-user's browser which will provide access to streams in a space with secure streaming enabled. Parameters provide ways to further limit access to streaming content. Rather than returning the cookies, this call stores them and returns a URL through which the cookies can be retrieved and set.


No Format
{
  "spaceId" : "",
  "minutesToExpire" : "",
  "ipAddress" : "",
  "redirectUrl" : ""
}

spaceId - Name of the space in which the streamed content is stored

minutesToExpire - Number of minutes until the generated cookies expires and streams can no longer be played (optional, default is 480)

ipAddress - IP address range where requests to stream must originate, in CIDR notation (e.g. 1.2.3.4/32) (optional)

redirectUrl - The URL the user should be redirected to after visiting the signed cookies URL

 


No Format
{
  "signedCookiesUrl" : ""
}

signedCookiesUrl - A URL to which the end user can be sent in order for signed cookies to be set in their browser

RTMP Streaming support (Deprecated as of DuraCloud 5.0.0)

taskName

Name

Description

Request Body

Response Body

enable-streaming

Enable Streaming task

Enables RTMP streaming for all files within a DuraCloud space through the use of Amazon's Cloudfront streaming capability. This task may take up to 15 minutes to complete.

When this call completes, two new properties will have been added to the set of properties for the specified space:

  • streaming-host - this is the RTMP host value, which can be used to generate URLs for open streams
  • streaming-type - will either be OPEN or SECURE, depending on the value of the secure parameter provided when streaming was enabled


No Format
{
  "spaceId" : "",
  "secure" : ""
}

spaceId - Name of the space for which streaming is to be enabled

secure - true or false, should streaming be secured


No Format
{
  "result" : "",
  "streamingHost" : ""
}

result - Text indicating the results of the task

streamingHost - the host name of the streaming endpoint

disable-streaming

Disable Streaming task

Disables streaming by removing the ability for Cloudfront to access files within a space. This does not remove the streaming distribution, only disables its use, so enabling streaming on the same space again can be performed much more quickly. Some content in the space may continue to be available for streaming up to 24 hours after streaming has been disabled.


No Format
{
  "spaceId" : ""
}

spaceId - Name of the space for which streaming is to be disabled


No Format
{
  "result" : ""
}

result - Text indicating the results of the task

delete-streaming

Delete Streaming task

Removes a streaming distribution created by the enable-streaming task. This task should be performed after performing the disable-streaming task. This task may take up to 15 minutes to complete, after which no content in the space will be available for streaming.


No Format
{
  "spaceId" : ""
}

spaceId - Name of the space for which streaming is to be deleted


No Format
{
  "result" : ""
}

result - Text indicating the results of the task

get-urlGet URL task

Retrieves a URL for a media file that is streamed through Cloudfront via an open distribution


No Format
{
  "spaceId" : "",
  "contentId" : "",
  "resourcePrefix" : ""
}

spaceId - Name of the space in which the streamed content is stored

contentId - Name of the content item to be streamed

resourcePrefix - A prefix on the content item which may be required by the streaming viewer. (e.g. an mp4 file may need a prefix of "mp4:") (optional)

 


No Format
{
  "streamUrl" : ""
}

streamUrl - The URL to be used for streaming the requested content

get-signed-urlGet Signed URL task

Retrieves a signed URL for a media file that is streamed through Cloudfront via a secure distribution


No Format
{
  "spaceId" : "",
  "contentId" : "",
  "minutesToExpire" : "",
  "ipAddress" : ""
  "resourcePrefix" : ""
}

spaceId - Name of the space in which the streamed content is stored

contentId - Name of the content item to be streamed

minutesToExpire - Number of minutes until the generated URL expires and the stream can no longer be played (optional, default is 480)

ipAddress - IP address range where requests to stream must originate, in CIDR notation (e.g. 1.2.3.4/32) (optional)

resourcePrefix - A prefix on the content item which may be required by the streaming viewer. (e.g. an mp4 file may need a prefix of "mp4:") (optional)

 


No Format
{
  "signedUrl" : ""
}

signedUrl - The URL to be used for streaming the requested content

Storage Policy support

taskName

Name

Description

Request Body

Response Body

set-storage-policySet Storage PolicySets the S3 bucket lifecycle policies associated with a given space. This task is restricted to DuraCloud service administrators.


No Format
{
  "spaceId" : "",
  "storageClass" : "",
  "daysToTransition" : 0
}

spaceId - Name of the space for which the storage policy should be set

storageClass - One of "STANDARD_IA", "REDUCED_REDUNDANCY", or "GLACIER"

daysToTransition - Number of days content should remain at standard storage before being transitioned to the new storage class

 


No Format
{
  "result" : ""
}

result - Text indicating the results of the task

noop

Test task

Provides a simple way to test the calling of tasks

None

"Success"

Amazon Glacier Storage Provider

taskName

Name

Description

Request Body

Response Body
restore-contentRestore Content taskProvides the capability to request that specific content items stored in Glacier be retrieved. Content items which are retrieved are made available 3-5 hours after this request is made, and remains available for 2 weeks.Name of the space and the content item in the form: spaceID/contentIDText indicating that a restore action has been initiated (or that a restore is already in progress, in the case of duplicate requests.)
Snapshot Storage Provider

taskName

Name

Description

Request Body

Response Body
create-snapshotCreate Snapshot taskCreates a snapshot by collecting details of the snapshot and passing the request down to a bridge application which makes a copy of the contents of the space.


No Format
{
  "spaceId" : "",
  "description" : "",
  "userEmail" : ""
}



No Format
{
  "snapshotId" : "",
  "status" : ""
}


get-snapshotGet Snapshot taskRetrieves the status and details of a snapshot action


No Format
{
  "snapshotId" : ""
}



No Format
{
  "snapshotId" : "",
  "snapshotDate" : "",
  "status" : "",
  "sourceHost" : "",
  "sourceSpaceId" : "",
  "sourceStoreId" : "",
  "description" : "",
  "contentItemCount" : "",
  "totalSizeInBytes" : ""
  "alternateIds" :
    ["" , ""]    
}


cleanup-snapshotClean Up Snapshot taskHandles the removal of content items in a space after a snapshot has taken place


No Format
{
  "spaceId" : ""
}



No Format
{
  "contentExpirationDays" : ""
}


complete-snapshotComplete Snapshot taskCompletes the snapshot process


No Format
{
  "spaceId" : ""
}



No Format
{
  "result" : ""
}


complete-cancel-snapshotComplete the cancellation of a snapshotHandles the removal of any space properties, .collection-snapshot.properties file, and snapshot related user permissions. It should be called by the bridge after it has finished its cancellation process.


No Format
{
  "spaceId" : ""
}



No Format
{
  "result" : "text description of result"
}


restart-snapshotRestart Snapshot taskRestarts the snapshot process if a failure occurred while transferring from DuraCloud to the bridge.


No Format
{
  "snapshotId" : ""  
}

 

 


No Format
{
  "snapshotId" : "",
  "status" : ""
}


get-snapshotsGet List of Snapshots taskRetrieves a listing of all snapshots which have been createdNone


No Format
{
  "snapshots" : [
    {
      "snapshotId" : "",  
      "description" : "",
      "status" : ""
    }, 
    ...,
    ...  
  ]
}


get-snapshot-contentsGet List of Snapshot Contents taskRetrieves a listing of the contents of a particular snapshot


No Format
{
  "snapshotId" : "",
  "pageNumber" : 0,
  "pageSize" : 1000,
  "prefix" : ""
}



No Format
{ 
  "totalCount" : 0,
  "contentItems" : 
  [{ 
    "contentId" : "",
    "contentProperties" : 
      {
        "" : ""
      }
  }]
}


get-snapshot-historyGet Snapshot History taskRetrieves a listing of events which have occurred in the history of a particular snapshot


No Format
{
  "snapshotId" : "",
  "pageNumber" : 0,
  "pageSize" : 0
}



No Format
{
  "totalCount" : 0,
  "historyItems" : 
  [{ 
    "history" : "",
    "historyDate" : 0
  }]
}


request-restore-snapshot

Request a snapshot restoreSends a restore request to an duracloud admin level user. This call can be made by user with access to the snapshot in question. Action on the part of the admin receiving the request is required to initiate a restore. The value of the user email address parameter will be used for notification purposes once the restore begins.


No Format
{
  "snapshotId" : "",
  "userEmail" : ""
}



No Format
{
  "description" : ""
}


restore-snapshotRestore Snapshot taskInitiates the restoration of a snapshot to a DuraCloud space. This call requires admin access.


No Format
{
  "snapshotId" : "",
  "userEmail" : ""
}



No Format
{
  "spaceId" : "",
  "restoreId" : "",
  "status" : ""
}


complete-restoreComplete Restore taskCompletes the restoration action by setting up an expiration policy for restored content


No Format
{
  "spaceId" : "",                         
  "daysToExpire" : 1
}



No Format
{
  "result" : ""
}


get-restoreGet Snapshot Restore task

Retrieves the status and details of a restore action. Note that you must specify either the snapshotId or the restoreId, but not both. Specifying the snapshotId will return the most recent restoration matching that snapshotId. Specifying the restoreId you will get back the restoration matching that ID (as you would expect).


No Format
{
  "snapshotId" : "",
  "restoreId" : ""
}



No Format
{
  "restoreId" : "",
  "snapshotId" : "",
  "status" : "",
  "startDate" : "",
  "endDate" : "",
  "statusText" : "",
  "destinationHost" : "",
  "destinationPort" : "",
  "destinationStoreId" : "",
  "destinationSpaceId" : ""
}



...