DuraCloud REST API

Initialize Security Users

• Purpose: Allows the initialization of authorized users
• Request:
  • POST https://host:port/durastore/security
  • POST https://host:port/duraservice/security
  • POST https://host:port/duradmin/security

• Request Body: XML similar to:

  <dur:security-users schemaVersion="0.2" xmlns:dur="duracloud.org">
    <security-user>
      <username>username-0</username>
      <password>password-0</password>
      <enabled>true</enabled>
      <accountNonExpired>true</accountNonExpired>
      <credentialsNonExpired>true</credentialsNonExpired>
      <accountNonLocked>true</accountNonLocked>
      <grantedAuthorities>ROLE_USER</grantedAuthorities>
    </security-user>
    <security-user>
      <username>username-1</username>
      <password>password-1</password>
      <enabled>false</enabled>
      <accountNonExpired>false</accountNonExpired>
      <credentialsNonExpired>false</credentialsNonExpired>
      <accountNonLocked>false</accountNonLocked>
      <grantedAuthorities>ROLE_USER ROLE_ADMIN</grantedAuthorities>
    </security-user>
  </dur:security-users>
  

• Response Code: 200 (on success)
• Response Body: "Initialization Successful" (on success)

Initialize Stores

• Purpose: Allows the initialization of storage provider accounts
• Request: POST https://host:port/durastore/init

• Request Body: XML similar to:

  <durastoreConfig>
    <storageAudit>
      <auditUsername>audit-username</auditUsername>
      <auditPassword>audit-password</auditPassword>
      <auditQueue>audit-queue-name</auditQueue>
      <auditLogSpaceId>audit-log-space-id</auditLogSpaceId>
    </storageAudit>
    <millDb>
      <name>db-name</name>
      <host>db-host</name>
      <port>db-port</name>
      <username>db-username</username>
      <password>db-password</password>
    </millDb>
    <storageProviderAccounts>
      <storageAcct ownerId='0' isPrimary='true'>
        <id>1</id>
        <storageProviderType>AMAZON_S3</storageProviderType>
        <storageProviderCredential>
          <username>username</username>
          <password>password</password>
        </storageProviderCredential>
        <storageProviderOptions>
          <!-- Provider specific details -->
        </storageProviderOptions>
      </storageAcct>
    </storageProviderAccounts>
  </durastoreConfig>

• Response Code: 200 (on success)
• Response Body: "Initialization Successful" (on success)

Is Initialized

• Purpose: Performs a check to determine if the DuraStore application has been initialized
• Request: GET https://host:port/durastore/init
• Response Code: 200 (if the application has been initialized), 503 (if the application has NOT been initialized)
• Response Body: Text indicating whether initialization has occurred.

Get Stores

• Purpose: Provides a listing of available storage providers accounts (without credentials)
• Request: GET https://host:port/durastore/stores
• Parameters: None
• Response Code: 200 (on success)

• Response Body: XML similar to:

  <storageProviderAccounts>
    <storageAcct isPrimary='true'>
      <id>1</id>
      <storageProviderType>AMAZON_S3</storageProviderType>
    </storageAcct>
    <storageAcct isPrimary="false">
      <id>2</id>
      <storageProviderType>RACKSPACE</storageProviderType>
    </storageAcct>
  </storageProviderAccounts>
  

Get Spaces

• Purpose: Provides a listing of all of the spaces that a customer has created
• Request: GET https://host:port/durastore/spaces ? (storeID)
• Response Code: 200 (on success)

• Response Body: XML similar to:

  <spaces>
    <space id="space1" />
    <space id="space2" />
  </spaces>
  

Get Space

• Purpose: Provides a listing of the contents of a space along with space properties
• Request: GET https://host:port/durastore/spaceID ? (storeID) (prefix) (maxResults) (marker)
  
  • storeID (optional) - ID of the content storage provider to query (default is primary store)
  • prefix (optional) - Only retrieve content ids with this prefix (default is all content ids)
  • maxResults (optional) - The maximum number of content IDs to return in the list (default is 1000)
    note: the maximum allowable value for maxResults is 1000. Any larger value will be reduced to 1000.
  • marker (optional) - The content ID marking the last item in the previous set (default is the first set of ids)
• Response Code: 200 (on success)

• Response Body: XML similar to:

  <space id="space1">
    <item>Image 1</item>
    <item>Image 2</item>
  </space>
  

• Response Headers: All available space properties, example:

  x-dura-meta-space-count: 65
  x-dura-meta-space-created: Mon, 01 Jan 2000 08:00:00 EST
  

Get Space Properties

• Purpose: Provides all space properties
• Request: HEAD https://host:port/durastore/spaceID ? (storeID)
• Response Code: 200 (on success)
• Response Headers: Same as for Get space (above)

Get Space ACLs

• Purpose: Provides all space ACLs, with values of 'r' (read) and 'w' (read/write)
• Request: HEAD https://host:port/durastore/acl/spaceID ? (storeID)
• Response Code: 200 (on success)

• Response Headers: All available space ACLs, example:

  x-dura-meta-acl-user0: WRITE
  x-dura-meta-acl-user1: WRITE
  x-dura-meta-acl-group-curators: READ
  

Create Space

• Purpose: Creates a new space
• Request: PUT https://host:port/durastore/spaceID ? (storeID)

• Response Code: 201 (on success)

• Response Headers: Location of the new space (i.e. the URL used to create the space), example:

  Location: https://myhost:8080/durastore/space1

Set Space ACLs

• Purpose: Updates the ACLs associated with a space
• Request: POST https://host:port/durastore/acl/spaceID ? (storeID)

• Request Headers: For 'user' ACLs the header prefix must be 'x-dura-meta-acl-' and for 'groups' the header prefix must be 'x-dura-meta-acl-group-'. Allowable values for ACL headers are: 'READ' and 'WRITE'.
  Example:

  x-dura-meta-acl-user0: WRITE
  x-dura-meta-acl-user1: WRITE
  x-dura-meta-acl-group-curators: READ
  

• Response Code: 200 (on success)
• Response Body: "Space $spaceID ACLs updated successfully" (on success)

Delete Space

• Purpose: Deletes a space
• Request: DELETE https://host:port/durastore/spaceID ? (storeID)
• Response Code: 200 (on success)
• Response Body: "Space $spaceID deleted successfully" (on success)

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
• Response Code: 200 (on success)
• Response Body: The content stream

• Response Headers: All available content properties, example:

  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:

  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:

    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.

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:

  x-dura-meta-copy-source: space-id/content-id
  

• Optional Request Headers: Copy source store, example:

  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:

    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"

Get Audit Log

• Purpose: Returns the latest audit for a given store and space
• Request: GET https://host:port/durastore/audit/{spaceId} ? (storeID)
  • Optional parameter 'storeID': if not set, primary store storage provider is used.
• Response Code: 200 (on success), 404 if audit logs were not found.

• Response Body: TSV in chronological order with the following fields.

  ACCOUNT	STORE_ID	SPACE_ID	CONTENT_ID	CONTENT_MD5	CONTENT_SIZE	CONTENT_MIMETYPE	CONTENT_PROPERTIES	SPACE_ACLS	SOURCE_SPACE_ID	SOURCE_CONTENT_ID	TIMESTAMP	ACTION	USERNAME
  mysubdomain	51	myspace	image-01.jpg	b1978f9fc4fe9448e05b83bbe6b98109	81214	image/jpeg	{"content-mimetype" : "image/jpeg"}		{}		2014-09-10T15:54:42.042	ADD_CONTENT	root

Get Manifest

• Purpose: Returns the manifest for a given space and storeId
• Request: GET https://host:port/durastore/manifest/{spaceId} ? (storeID) (format)
  • Optional parameter 'storeID': if not set, primary store storage provider is used.
  • Optional parameter 'format': TSV or BAGIT. TSV is default.

• Response Code: 200 (on success), 404 if manifest was empty found.

• Response Body: TSV in chronological order with the following fields.

  TSV results

  space-id	content-id	MD5
  auditlogs	localhost/51/auditlogs/localhost_51_auditlogs-2014-09-10-15-56-07.tsv	6992f8e57dafb17335f766aa2acf5942
  auditlogs	localhost/51/photos/localhost_51_photos-2014-09-10-15-55-01.tsv	820e786633fb495db447dc5d5cf0b2bd
  
  

Get Latest Bit Integrity Report

• Purpose: Returns the latest bit integrity report for a given space and store
• Request: GET https://host:port/durastore/bit-integrity/{spaceId} ? (storeID)
  • Optional parameter 'storeID': if not set, primary store storage provider is used.

• Response Code: 200 (on success), 404 if manifest was empty found.

• Response Head contains the following fields
  • Bit-Integrity-Report-Completion-Date: yyyy-MM-ddTHH:mm:ss
  • Bit-Integrity-Report-Result: (SUCCESS or FAILURE)

• Response Body: TSV with the following fields.

  TSV results

  date-checked	account	store-id	store-type	space-id	content-id	result	content-checksum	provider-checksum	manifest-checksum	details

  In order to retrieve just the headers use the HEAD http method.

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:

  <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

{
  "spaceId" : "",
  "secure" : ""
}

{
  "result" : "",
  "streamingHost" : ""
}

{
  "spaceId" : ""
}

{
  "result" : ""
}

{
  "spaceId" : ""
}

{
  "result" : ""
}

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

{
  "streamUrl" : ""
}

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

{
  "signedUrl" : ""
}

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

{
  "result" : ""
}

Amazon Glacier Storage Provider

Snapshot Storage Provider

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

{
  "snapshotId" : "",
  "status" : ""
}

{
  "snapshotId" : ""
}

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

{
  "spaceId" : ""
}

{
  "contentExpirationDays" : ""
}

{
  "spaceId" : ""
}

{
  "result" : ""
}

{
  "spaceId" : ""
}

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

{
  "snapshotId" : ""  
}

{
  "snapshotId" : "",
  "status" : ""
}

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

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

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

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

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

{
  "snapshotId" : "",
  "userEmail" : ""
}

{
  "description" : ""
}

{
  "snapshotId" : "",
  "userEmail" : ""
}

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

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

{
  "result" : ""
}

{
  "snapshotId" : "",
  "restoreId" : ""
}

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

Initialize Application

• Purpose: Allows the initialization of duradmin
• Request: POST https://host:port/duradmin/init

• Request Body: XML similar to:

  <duradminConfig>
    <durastoreHost>[host]</durastoreHost>
    <durastorePort>[port]</durastorePort>
    <durastoreContext>durastore</durastoreContext>
    <duraserviceHost>[host]</duraserviceHost>
    <duraservicePort>[port]</duraservicePort>
    <duraserviceContext>duraservice</duraserviceContext>
    <!--optional-->
    <millDbEnabled>[true or false]</millDbEnabled>
  </duradminConfig>
  

• Response Code: 200 (on success)
• Response Body: "Initialization Successful" (on success)

Is Initialized

• Purpose: Performs a check to determine if the DurAdmin application has been initialized
• Request: GET https://host:port/duradmin/init
• Response Code: 200 (if the application has been initialized), 503 (if the application has NOT been initialized)
• Response Body: Text indicating whether initialization has occurred.

Initialize Application

• Purpose: Allows the initialization of duraboss
• Request: POST https://host:port/duraboss/init

• Request Body: XML similar to:

  <durabossConfig>
    <reporterEnabled>[true|false]</reporterEnabled>
    <durastoreHost>[host]</durastoreHost>
    <durastorePort>[port]</durastorePort>
    <durastoreContext>durastore</durastoreContext>
    <notificationConfig>
      <type>EMAIL</type>
      <username>[username for notification system]</username>
      <password>[password for notification system]</password>
      <originator>[from email address]</originator>
      <admin>[administrator email address]</admin>
    </notificationConfig>
  </durabossConfig>
  

• Response Code: 200 (on success)
• Response Body: "Initialization Successful" (on success)

Is Initialized

• Purpose: Performs a check to determine if the DuraBoss application has been initialized
• Request: GET https://host:port/duraboss/init
• Response Code: 200 (if the application has been initialized), 503 (if the application has NOT been initialized)
• Response Body: Text indicating whether initialization has occurred.

Get Latest Storage Report

• Purpose: Provides the most current storage report in XML format
• Request: GET https://host:port/duraboss/report/storage
• Response Code: 200 (on success)
• Response Body: XML, defined by the storage report XSD

Get Storage Report List

• Purpose: Provides a list of all storage report IDs
• Request: GET https://host:port/duraboss/report/storage/list
• Response Code: 200 (on success)
• Response Body: XML, defined by the storage report XSD

Get Storage Report

• Purpose: Provides a specific storage report based on the provided report ID
• Request: GET https://host:port/duraboss/report/storage/reportID
• Response Code: 200 (on success)
• Response Body: XML, defined by the storage report XSD

Get Storage Report Info

• Purpose: Provides a information about the current status of the storage reporting system
• Request: GET https://host:port/duraboss/report/storage/info
• Response Code: 200 (on success)
• Response Body: XML, defined by the storage report XSD

Start Storage Report

• Purpose: Starts a storage report if one is not already running
• Request: POST https://host:port/duraboss/report/storage
• Response Code: 200 (on success)
• Response Body: "Report Started" (on success), or ""Report Already In Progress" (if a report is already in progress)

Cancel Storage Report

• Purpose: Cancels a running storage report
• Request: DELETE https://host:port/duraboss/report/storage
• Response Code: 200 (on success)
• Response Body: "Storage report cancelled"

Schedule Storage Report

• Purpose: Schedules a time for a storage report to be run
• Request: POST https://host:port/duraboss/report/storage/schedule ? (startTime) (frequency)
  
  • startTime: time (in milliseconds since the epoch) to begin the next storage report
  • frequency: time (in milliseconds) to wait between running reports (minimum value is 600000)
• Response Code: 200 (on success)
• Response Body: "Storage reports scheduled" (on success)

Cancel Storage Report Schedule

• Purpose: Cancels all entries on the storage report schedule
• Request: DELETE https://host:port/duraboss/report/storage/schedule
• Response Code: 200 (on success)
• Response Body: "Storage Reports schedule cancelled"