DuraCloud REST API methods:
Notes
Each of the methods below has specific security requirements. See DuraCloud Security for more information
Due to an issue which does not properly handle requests redirected from http to https, it is recommended that all REST API requests use https directly.
Examples calling the API defined below with the Unix utility "curl" can be found here
All Applications
Initialize Security Users
- Purpose: Allows the initialization of authorized users
- Request:
- Request Body: XML similar to:
<?xml version="1.0" encoding="UTF-8"?> <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)
DuraStore
Purpose: DuraStore is the application through which DuraCloud manages storage. The DuraStore REST API provides access to storage by mediating the underlying storage provider APIs to allow access to multiple cloud storage options through a single API.
Initialize Stores
- Purpose: Allows the initialization of storage provider accounts
- Request: POST https://host:port/durastore/stores
- Request Body: XML similar to:
<storageProviderAccounts> <storageAcct ownerId='0' isPrimary='true'> <id>1</id> <storageProviderType>AMAZON_S3</storageProviderType> <storageProviderCredential> <username>username</username> <password>password</password> </storageProviderCredential> </storageAcct> </storageProviderAccounts>
- Response Code: 200 (on success)
- Response Body: "Initialization Successful" (on success)
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-access: OPEN x-dura-meta-space-created: Mon, 01 Jan 2000 08:00:00 EST x-dura-meta-custom-property: Custom Property Value
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)
Create Space
- Purpose: Creates a new space
- Request: PUT https://host:port/durastore/spaceID ? (storeID)
- Request Headers: Properties about the space, example:
x-dura-meta-space-access: OPEN x-dura-meta-custom-property: Custom Property Value
- 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 Properties
- Purpose: Updates the properties associated with a space
- Request: POST https://host:port/durastore/spaceID ? (storeID)
- Request Headers: Same as Create space (above)
- Response Code: 200 (on success)
- Response Body: "Space $spaceID 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
- Note that 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.
- 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: b1946ac92492d2347c6235b4d2611184 ETag: b1946ac92492d2347c6235b4d2611184 Location: https://myhost:8080/durastore/space1/content1
Set Content Properties
- Purpose: Updates the properties associated with a piece of content
- 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"
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:
<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
taskName |
Storage Provider |
Name |
Description |
Request Body |
Response Body |
---|---|---|---|---|---|
enable-streaming |
Amazon S3 |
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. |
Name of the space for which streaming is to be enabled |
Text indicating the results of the task, including the streaming host |
disable-streaming |
Amazon S3 |
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. |
Name of the space for which streaming is to be disabled |
Text indicating the results of the task |
delete-streaming |
Amazon S3 |
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. |
Name of the space for which streaming is to be deleted |
Text indicating the results of the task |
run-hadoop-job |
Amazon S3 |
Run Hadoop Job task |
Runs a hadoop job using Amazon's Elastic Map Reduce feature. A JAR which implements the hadoop interfaces is expected to have already been loaded into S3. This JAR is used to execute the hadoop job. |
A map serialized into XML which includes, at a minimum, values for jarContentId, sourceSpaceId, destSpaceId, and workSpaceId. |
A map serialized into XML which includes the jobFlowId |
describe-hadoop-job |
Amazon S3 |
Describe Hadoop Job task |
Retrieves information about a hadoop job running in Amazon's Elastic Map Reduce |
The Job Flow ID |
A map serialized into XML which includes information about the running job |
stop-hadoop-job |
Amazon S3 |
Stop Hadoop Job task |
Stops a hadoop job running in Amazon's Elastic Map Reduce |
The Job Flow ID |
A map serialized into XML which includes a results key with a value of either success or failure |
noop |
Amazon S3 |
Test task |
Provides a simple way to test the calling of tasks |
Body content is ignored |
Text indicating successful task completion |
DuraService
Purpose: DuraService is the application through which DuraCloud manages services. The DuraService REST API provides the means by which services available in the DuraCloud service repository are deployed, configured, and undeployed.
Resources: XML schema which define the service configuration can be found on the Downloads page
Initialize Services
- Purpose: Initializes the DuraService application
- Request: POST https://host:port/duraservice/services
- Request Body: XML similar to:
<servicesConfig> <primaryServiceInstance> <host>[PRIMARY-SERVICE-INSTANCE-HOST]</host> <servicesAdminPort>[PRIMARY-SERVICES-ADMIN-PORT]</servicesAdminPort> <servicesAdminContext>[PRIMARY-SERVICES-ADMIN-CONTEXT]</servicesAdminContext> </primaryServiceInstance> <userStorage> <host>[USER-STORAGE-HOST-NAME]</host> <port>[USER-STORAGE-PORT]</port> <context>[USER-STORAGE-CONTEXT]</context> <msgBrokerUrl>[USER-STORAGE-MSG-BROKER-URL]</msgBrokerUrl> </userStorage> <serviceStorage> <host>[SERVICES-STORAGE-HOST-NAME]</host> <port>[SERVICES-STORAGE-PORT]</port> <context>[SERVICES-STORAGE-CONTEXT]</context> <spaceId>[SERVICES-STORAGE-SPACE-ID]</spaceId> </serviceStorage> <serviceCompute> <type>AMAZON_EC2</type> <imageId>[MACHINE-IMAGE-ID]</imageId> <computeProviderCredential> <username>[USERNAME]</username> <password>[PASSWORD]</password> </computeProviderCredential> </serviceCompute> </servicesConfig>
- Response Code: 200 (on success)
- Response Body: "Initialization Successful" (on success)
Get Services
- Purpose: Retrieves a listing of services, along with their configuration options
- Request: GET https://host:port/duraservice/services ? (show)
- Parameter options for show (optional)
- available (default) - Includes only services which have not been deployed but are available for deployment
- deployed - Includes only services which have been deployed and started
- Parameter options for show (optional)
- Response Code: 200 (on success)
- Response Body: XML list of services (see service config xsd)
Get Service
- Purpose: Retrieves information about a particular service including description, configuration options, and all deployments
- Request: GET https://host:port/duraservice/serviceID
- Response Code: 200 (on success)
- Response Body: XML service (see service config xsd)
Get Deployed Service
- Purpose: Retrieves information about a deployed service including description, configuration options, and a single deployment indicating the configuration options in use
- Request: GET https://host:port/duraservice/serviceID/deploymentID
- Response Code: 200 (on success)
- Response Body: XML service (see service config xsd)
Get Deployed Service Properties
- Purpose: Retrieves the runtime properties of a deployed service
- Request: GET https://host:port/duraservice/serviceID/deploymentID/properties
- Response Code: 200 (on success)
- Response Body: XML service (simple xml Map serialization)
Deploy Service
- Purpose: Deploys and starts an available service
- Request: PUT https://host:port/duraservice/serviceID ? (serviceHost)
- Parameter value for serviceHost (optional) should indicate the services host on which the service should be deployed. Default is the primary customer host.
- Request Body: XML user configuration indicating the config selections for the service (see user config portion of service config xsd)
- Response Code: 201 (on success)
- Response Header: Location header indicates the URL at which information about the deployed service can be retrieved (the URL for a get deployed service call) which includes the deploymentID
Update Service Configuration
- Purpose: Updates the configuration of a deployed service
- Request: POST https://host:port/duraservice/serviceID/deploymentID
- Request Body: Updated XML user configuration indicating the config selections for the service (see user config portion of service config xsd)
- Response Code: 200 (on success)
UnDeploy Service
- Purpose: Stops and Undeploys a deployed service
- Request: DELETE https://host:port/duraservice/serviceID/deploymentID
- Response Code: 200 (on success)
DurAdmin
Purpose: DurAdmin is the user-facing application through which DuraCloud exposes DuraStore and DuraService functionality. The DurAdmin REST API provides the means by which DurAdmin is initialized.
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> </duradminConfig>
- Response Code: 200 (on success)
- Response Body: "Initialization Successful" (on success)
DuraReport
Purpose: DuraReport generates reports relating to the status of your DuraCloud instance, and provides a simple interface for accessing those reports.
Initialize Application
- Purpose: Allows the initialization of durareport
- Request: POST https://host:port/durareport/reports
- Request Body: XML similar to:
<durareportConfig> <durastoreHost>[host]</durastoreHost> <durastorePort>[port]</durastorePort> <durastoreContext>durastore</durastoreContext> <duraserviceHost>[host]</duraserviceHost> <duraservicePort>[port]</duraservicePort> <duraserviceContext>duraservice</duraserviceContext> </durareportConfig>
- Response Code: 200 (on success)
- Response Body: "Initialization Successful" (on success)
Get Latest Storage Report
- Purpose: Provides the most current storage report in XML format
- Request: GET https://host:port/durareport/storagereport
- 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/durareport/storagereport/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/durareport/storagereport/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/durareport/storagereport/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/durareport/storagereport
- 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/durareport/storagereport
- 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/durareport/storagereport/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/durareport/storagereport/schedule
- Response Code: 200 (on success)
- Response Body: "Storage Reports schedule cancelled"
Get Deployed Services Report
- Purpose: Provides a listing of the services which are currently deployed
- Request: GET https://host:port/durareport/storagereport/deployed
- Response Code: 200 (on success)
- Response Body: XML, defined by the service report XSDs
Get Completed Services Report
- Purpose: Provides a listing of the most recent completed services
- Request: GET https://host:port/durareport/servicereport ? (limit)
- Parameter value for limit (optional) should indicate the maximum number of services to return in the report (default is 20, max is 1000)
- Response Code: 200 (on success)
- Response Body: XML, defined by the service report XSDs
Get Completed Services Report List
- Purpose: Provides a listing of all service report IDs
- Request: GET https://host:port/durareport/servicereport/list
- Response Code: 200 (on success)
- Response Body: XML, defined by the service report XSDs
Get Services Report
- Purpose: Provides a specific services report based on the provided report ID
- Request: GET https://host:port/durareport/servicereport/reportID
- Response Code: 200 (on success)
- Response Body: XML, defined by the service report XSDs