docs.rackspace.com/api

Transcription

1 docs.rackspace.com/api

2 Rackspace Cloud Backup Getting API v1.0 ( ) 2015 Rackspace US, Inc. This document is intended for software developers interested in developing applications using the Rackspace Cloud Backup Application Programming Interface (API). The document is for informational purposes only and is provided AS IS. RACKSPACE MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, AS TO THE ACCURACY OR COM- PLETENESS OF THE CONTENTS OF THIS DOCUMENT AND RESERVES THE RIGHT TO MAKE CHANGES TO SPECIFICATIONS AND PROD- UCT/SERVICES DESCRIPTION AT ANY TIME WITHOUT NOTICE. RACKSPACE SERVICES OFFERINGS ARE SUBJECT TO CHANGE WITH- OUT NOTICE. USERS MUST TAKE FULL RESPONSIBILITY FOR APPLICATION OF ANY SERVICES MENTIONED HEREIN. EXCEPT AS SET FORTH IN RACKSPACE GENERAL TERMS AND CONDITIONS AND/OR CLOUD TERMS OF SERVICE, RACKSPACE ASSUMES NO LIABILITY WHATSOEVER, AND DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO ITS SERVICES INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. Except as expressly provided in any written license agreement from Rackspace, the furnishing of this document does not give you any license to patents, trademarks, copyrights, or other intellectual property. Rackspace, Rackspace logo and Fanatical Support are registered service marks of Rackspace US, Inc. All other product names and trademarks used in this document are for identification purposes only and are property of their respective owners. ii

3 Table of Contents 1. Overview Prerequisites for running examples Pricing and service level Send requests to the API Sending API requests by using curl Copying and pasting curl request examples into a terminal window Service access endpoints Generate an authentication token Create and work with backups List all agents for the user List agent details Create a backup configuration List all backup configurations for an agent Update a backup configuration Start a backup manually Checking backup status List activity for an agent Create a restore configuration Start a restore operation manually Get a restore report Delete a backup configuration Additional resources Document change history Glossary iii

4 List of Tables 2.1. curl command-line options Regionalized service endpoints... 6 iv

5 List of Examples 2.1. Example curl authentication request curl authentication request: JSON Authentication response with partial service catalog showing Cloud Backup endpoints List all agents for the user List agent details Create a backup configuration List all backup configurations for an agent Update a backup configuration Start a backup manually Checking backup status List activity for an agent Create a restore configuration Start a restore manually Get a restore report Delete a backup configuration List backup configuration details v

6 1. Overview The Rackspace Cloud Backup service enables you to select and back up specific files and folders from your cloud server. You can schedule any number of backup jobs and restore to the same system or a different one, which gives you the flexibility and power to work with your schedule and your data. Using the Cloud Backup RESTful API, you can automate backup jobs while provisioning new servers. Merged into a Chef cookbook or in any other automation system, backups are a part of the deployment rather than something to consider and handle later. Key features are as follows: Select the files and folders from your server that you want to back up. Run your backups manually or on a schedule that works for you. See the activity from all your backups, both current and previous. Use AES-256 encryption with a private encryption key known only to you. Restore individual files and folders from a particular date. Save space with incremental backups that save only the changed portions of files. Create an unlimited number of backups. Note Cloud Backup does not take snapshots of your server. To read more about how Cloud Backup differs from snapshots, see "Rackspace Cloud Backup vs. Cloud Server Image Backups" in the Rackspace Knowledge Center. Follow the steps provided in this guide to use the Cloud Backup API to create backups and use them to restore your files and folders. The simple exercises in this guide help you get started with the API by using curl commands. With curl, you send HTTP requests with embedded API calls from the command line. The curl examples in this guide include request and response bodies in JSON format. For more information about curl, see Section 2.1, Sending API requests by using curl [3]. To use the API, it helps to be familiar with HTTP 1.1, RESTful web services, and JSON data serialization format. You can find details about the Cloud Backup API in the Rackspace Cloud Backup Developer Guide at For more details about Cloud Backup, go to This site also offers links to Rackspace official support channels, including phone, chat, and , as well as Knowledge Center articles. 1

7 1.1. Prerequisites for running examples To run the examples in this guide, you must have the following prerequisites: Rackspace Cloud account To sign up for a Rackspace Cloud account, go to the signup page. Rackspace Cloud user name and password, as specified during registration You also need to know your API key. To find your API key, use the following steps: 1. Log in to the Cloud Control Panel ( 2. On the upper-right side of the top navigation pane, click your username. 3. From the menu, select Account Settings. 4. In the Login Details section of the Account Settings page, locate the API Key field and click Show. 5. Copy the value of the API key and paste it into a text editor of your choice. 6. Click Hide to hide the value of the API key Pricing and service level Cloud Backup is part of the Rackspace Cloud and your use of the Cloud Backup API is billed according to the pricing schedule at Information about service level agreements (SLAs) is also available from that link. 2

8 2. Send requests to the API You have several options for sending requests through an API: Developers and testers might prefer to use curl, the command-line tool from curl.haxx.se/. With curl, you can send HTTP requests and receive responses back from the command line. curl is used in this guide. If you like to use a more graphical interface, the REST client for Mozilla Firefox works well for testing and trying out commands. See You can download and install RESTClient, a Java application used to test RESTful web services, from Sending API requests by using curl curl is a command-line tool that is available in UNIX system-based environments and Apple Mac OS X systems, and can be downloaded for Microsoft Windows to interact with REST interfaces. For more information about curl, see curl enables you to transmit and receive HTTP requests and responses from the command line or from within a shell script. As a result, you can work with the REST API directly without using one of the client APIs. The following curl command-line options are used in this guide to run the examples. Table 2.1. curl command-line options Option Description -d Sends the specified data in a POST request to the HTTP server. -i Includes the HTTP header in the output. -H HEADER Specifies an HTTP header in the request. You can specify any number of extra headers. Precede each header with the -H option. -s Specifies silent or quiet mode. No progress or error messages are shown. If your curl command is not generating any output, try replacing the -s option with -i. -X Specifies the request operation to use when communicating with the HTTP server. The specified request is used instead of the default operation, which is GET. For example, -X PUT specifies to use the PUT operation. Note If you have the tools, you can run the curl JSON request examples with the following option to format the output from curl: <curl JSON request example> python -m json.tool. 3

9 2.2. Copying and pasting curl request examples into a terminal window To run the curl request examples shown in this guide, perform the following actions: 1. Copy each example from the HTML version of this guide and paste it into an ASCII text editor (for example, vi or TextEdit). You can click on the small document icon to the right of each request example to select it. 2. Modify each example with your required account information and other information, as detailed in this guide. Note The carriage returns in the curl request examples are escaped with a backslash (\) character. The escape character allows continuation of the command across multiple lines. However, do not include the escape character in the JSON or XML request body within the curl command. 3. After you are finished modifying the text for the curl request example with your information (for example, user name and API key), copy and paste the text into your terminal window. 4. Press Enter to run the curl command. Consider the following example curl authentication request, which is described in detail in Chapter 4, Generate an authentication token [7]. Example 2.1. Example curl authentication request curl -s -X POST \ -H "Content-Type: application/json" \ -d ' "auth": "RAX-KSKEY:apiKeyCredentials": "username": "yourusername", "apikey": "yourapikey" ' python -m json.tool You can see that the lines that are part of the curl command syntax have all been escaped with a backslash (\) to indicate that the command continues on the next line: curl -s -X POST \ -H "Content-Type: application/json" \ -d ' (... lines within the JSON portion of the message are not shown in this example) (... the example shows only lines that are part of curl syntax) 4

10 ' python -m json.tool However, the lines within the JSON portion of the message are not escaped with a backslash, to avoid issues with the JSON processing. ' "auth": "RAX-KSKEY:apiKeyCredentials": "username": "yourusername", "apikey": "yourapikey" ' Tip If you have trouble copying and pasting the examples as described, try typing the entire example on one long line, removing all the backslash line-continuation characters. 5

11 3. Service access endpoints The Cloud Backup service is a regionalized service. The user of the service is responsible for appropriate replication, caching, and overall maintenance of Cloud Backup data across regional boundaries to other Cloud Backup servers. The following table lists the service endpoints for Cloud Backup. To help you decide which regionalized endpoint to use, read about special considerations for choosing a data center in the Knowledge Center article at About Regions. Table 3.1. Regionalized service endpoints Region Dallas/Ft. Worth (DFW) Chicago (ORD) London (LON) Hong Kong (HKG) Northern Virginia (IAD) Sydney (SYD) Endpoint Replace the sample account ID number (which is also called the tenant ID), , with your actual account number that is returned as part of the Cloud Identity service response. You will find the actual account number after the final slash ('/') in the publicurl field returned by the authentication response. Note The Cloud Backup API runs with or without the specification of the account ID number in the endpoint. However, the examples in this guide include the account number in the request URIs. 6

12 4. Generate an authentication token Your first step must always be to generate an authentication token. You must then include the authentication token in each request, in the X-Auth-Token header. Remember to replace the placeholders in the following authentication request example with your information: yourusername Your common Rackspace Cloud user name, as supplied during registration yourapikey Your API key See Section 1.1, Prerequisites for running examples [2] for the steps to use to find your API key. Note This guide uses yourusername and yourapikey for authentication. For information about other supported authentication methods, see Authentication tokens in the Cloud Identity Client Developer Guide. Use the following endpoint to access the Cloud Identity service for authentication, regardless of US or UK identities: Your account may be based in either the US or the UK. This is not determined by your physical location but by the location of the Rackspace retail site that was used to create your account: If your account was created via it is a US-based account. If your account was created via it is a UK-based account. Notice in Example 4.1, curl authentication request: JSON [8] that you authenticate using the URL for the Cloud Identity services identity.api.rackspacecloud.com/v2.0/tokens. The v2.0 component in the URL indicates that you are using version 2.0 of the Cloud Identity API. The curl request uses the -s option for silent or quiet mode (no progress or error messages shown), the -X option to specify the request operation to use when communicating with the HTTP server (instead of using the default operation), and the -d option to send the specified data in a POST request to the HTTP server. If you have the tools, you can run the curl JSON request examples with the following option to format the output from curl: <curl JSON request example> python -m json.tool. 7

13 Example 4.1. curl authentication request: JSON curl -s -X POST \ -H "Content-Type: application/json" \ -d ' "auth": "RAX-KSKEY:apiKeyCredentials": "username": "yourusername", "apikey": "yourapikey" ' python -m json.tool An HTTP status code of 200 (OK) indicates that the authentication request completed successfully. In the authentication response, the authentication token id is returned near the bottom of the following example with an expires attribute that specifies when the token expires. Tokens are valid for a finite duration, typically for 24 hours. Remember to supply your authentication token wherever you see the placeholder yourauthtoken in the examples in this guide. The publicurl endpoints for Cloud Backup (for example dfw.backup.api.rackspacecloud.com/v1.0/123456) are also returned in the authentication response. Your actual account number is after the final slash (/) in the publicurl field (for example in the preceding example endpoint). You must specify your account number in the Cloud Backup API request, wherever you see the placeholder youraccountid specified in the examples in this guide. Example 4.2. Authentication response with partial service catalog showing Cloud Backup endpoints "access": "servicecatalog": [ "endpoints": [ "publicurl": " rackspacecloud.com/v1/123456", "region": "SYD", "tenantid": "123456", "publicurl": " rackspacecloud.com/v1/123456", "region": "DFW", "tenantid": "123456", "publicurl": " rackspacecloud.com/v1/123456", "region": "ORD", "tenantid": "123456", 8

14 "publicurl": " rackspacecloud.com/v1/123456", "region": "IAD", "tenantid": "123456", "publicurl": " rackspacecloud.com/v1/123456", "region": "HKG", "tenantid": "123456" ], "name": "cloudblockstorage", "type": "volume", "endpoints": [ "publicurl": " v1.0/123456", "tenantid": "123456", "publicurl": " com/v1.0/123456", "region": "IAD", "tenantid": "123456", "publicurl": " com/v1.0/123456", "region": "HKG", "tenantid": "123456", "publicurl": " com/v1.0/123456", "region": "SYD", "tenantid": "123456", "publicurl": " com/v1.0/123456", "region": "DFW", "tenantid": "123456", "publicurl": " com/v1.0/123456", "region": "ORD", "tenantid": "123456" ], "name": "cloudbackup", "type": "rax:backup", "endpoints": [ 9

15 "publicurl": " com/v2/123456", "region": "SYD", "tenantid": "123456", "versionid": "2", "versioninfo": " rackspacecloud.com/v2", "versionlist": " rackspacecloud.com/", "publicurl": " com/v2/123456", "region": "DFW", "tenantid": "830866", "versionid": "2", "versioninfo": " rackspacecloud.com/v2", "versionlist": " rackspacecloud.com/", "publicurl": " com/v2/830866", "region": "IAD", "tenantid": "830866", "versionid": "2", "versioninfo": " rackspacecloud.com/v2", "versionlist": " rackspacecloud.com/", "publicurl": " com/v2/830866", "region": "HKG", "tenantid": "830866", "versionid": "2", "versioninfo": " rackspacecloud.com/v2", "versionlist": " rackspacecloud.com/", "publicurl": " com/v2/830866", "region": "ORD", "tenantid": "830866", "versionid": "2", "versioninfo": " rackspacecloud.com/v2", "versionlist": " rackspacecloud.com/" ], "name": "cloudserversopenstack", "type": "compute", ], "token": 10

16 "RAX-AUTH:authenticatedBy": [ "APIKEY" ], "expires": " T07:11:19.488Z", "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "tenant": "id": "123456", "name": "123456", "user": "RAX-AUTH:defaultRegion": "DFW", "id": "123456", "name": "yourusername", "roles": [ "description": "A Role that allows a user access to keystone Service methods", "id": "5", "name": "object-store:default", "tenantid": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeeeeeee", "description": "A Role that allows a user access to keystone Service methods", "id": "6", "name": "compute:default", "tenantid": "123456", "description": "User Admin Role.", "id": "3", "name": "identity:user-admin" ] After authentication, you can use curl to perform the GET, DELETE, PUT, and POST requests for the Cloud Backup API. 11

17 5. Create and work with backups This chapter contains simple examples of some basic Cloud Backup requests that you will commonly use. Example requests are provided in curl, followed by the response. For more information about all Cloud Backup operations, see the Rackspace Cloud Backup Developer Guide List all agents for the user The agent is an important component of Cloud Backup. You must install the agent on all servers that you want to back up. Documentation about installing agents is available from the link on Rackspace Control Panel under the Backup tab or at After the agent is installed on one or many servers, you can use the Cloud Backup API to configure your backups. Note If your account has the Managed Operations level of support, the Cloud Backup agent might already be installed on your server. If your cloud servers are listed under the Systems tab in the Backup section of the Cloud Control Panel, then the Cloud Backup agent is already installed. If it is not, Rackspace can install it for you. Check with your account manager. Assuming that you initially know nothing about the environment, in order to do anything with the backups, you need to list the agents. After you list them, you can choose the one you want to work with. MachineAgentId is what you need to work with the agent in other requests. The HTTP request must include a header to specify the authentication token. The curl request uses the -s option for silent or quiet mode (no progress or error messages shown) and the -X option to specify the request operation to use when communicating with the HTTP server (instead of using the default operation). If you have the tools, you can run the curl JSON request examples with the following option to format the output from curl: <curl JSON request example> python -m json.tool. An HTTP status code of 200 (OK) indicates that the request succeeded. Example 5.1. List all agents for the user curl -s -X GET user/agents \ -H "X-Auth-Token: yourauthtoken" python -m json.tool [ "AgentVersion": " ", "Architecture": "64-bit", 12

18 "BackupContainer": " com/v1/mossocloudfs_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/ z_do_not_delete_cloudbackup_v2_0_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "BackupDatacenter": "DFW", "BackupVaultSize": null, "CleanupAllowed": true, "Datacenter": "DFW", "Flavor": "RaxCloudServer", "HostServerId": "79aa4aa1-cd a6c4-6942b ", "IPAddress": " ", "IsDisabled": false, "IsEncrypted": false, "MachineAgentId": , "MachineName": "web2", "OperatingSystem": "Windows Server 2008 R2", "OperatingSystemVersion": "6.1", "PublicKey": "ExponentHex": 10001, "ModulusHex": "C6054E90E32D2B25E16F3A560E1B4DC580B1E4AB74E0C DD8A1BD F6A526B16C55225D1BE6E0B1265F4085FB2F61B61337F5D32198E5CAFFEA CD50E90517A329146E43B20194C082A9C890060AD07A542FBC035B2A96F9F212C6D94887BECB 5E15F3E55397B975B1896CFC66EBB5DD7D A0E7F669ADB925A7BE4C1ECED1BC9E92DB 768CE76FDC86CCDD04BDF469679FE3261AA66C22AC6263E540B79780AAF09CFC798CDC4D EA4BD1BF511E4881E07C5387DDDBE741E615ACA0C32A738F5B952F1C17051EC3BAF 9F64C629515EA2AF93E6BB450A8B1B3E D5670AF93CFEA649172EDA7AC5E071E2D 3AF0BD", "Status": "Unknown", "TimeOfLastSuccessfulBackup": null, "UseFailoverUri": false, "UseServiceNet": true ] 5.2. List agent details To check whether the agent is online, list the agent's details and check its status. If the agent is not online, Cloud Backup cannot run the backup job. Use MachineAgentId from Section 5.2, List agent details [13] for yourmachineagentid. The HTTP request must include a header to specify the authentication token. The curl request uses the -s option for silent or quiet mode (no progress or error messages shown) and the -X option to specify the request operation to use when communicating with the HTTP server (instead of using the default operation). If you have the tools, you can run the curl JSON request examples with the following option to format the output from curl: <curl JSON request example> python -m json.tool. An HTTP status code of 200 (OK) in the response indicates that the request succeeded. Example 5.2. List agent details curl -s -X GET agent/yourmachineagentid \ -H "X-Auth-Token: yourauthtoken" python -m json.tool 13

19 "AgentVersion": " ", "Architecture": "64-bit", "BackupContainer": " com/v1/mossocloudfs_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/ z_do_not_delete_cloudbackup_v2_0_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "BackupDatacenter": "DFW", "BackupVaultSize": "35.3 KB", "CleanupAllowed": true, "Datacenter": "DFW", "Flavor": "RaxCloudServer", "HostServerId": "79aa4aa1-cd a6c4-6942b ", "IPAddress": " ", "IsDisabled": false, "IsEncrypted": false, "MachineAgentId": , "MachineName": "web2", "OperatingSystem": "Windows Server 2008 R2", "OperatingSystemVersion": "6.1", "PublicKey": "ExponentHex": 10001, "ModulusHex": "C6054E90E32D2B25E16F3A560E1B4DC580B1E4AB74E0C DD8A1BD F6A526B16C55225D1BE6E0B1265F4085FB2F61B61337F5D32198E5CAFFEA CD50E90517A329146E43B20194C082A9C890060AD07A542FBC035B2A96F9F212C6D94887BECB 5E15F3E55397B975B1896CFC66EBB5DD7D A0E7F669ADB925A7BE4C1ECED1BC9E92DB 768CE76FDC86CCDD04BDF469679FE3261AA66C22AC6263E540B79780AAF09CFC798CDC4D EA4BD1BF511E4881E07C5387DDDBE741E615ACA0C32A738F5B952F1C17051EC3BAF 9F64C629515EA2AF93E6BB450A8B1B3E D5670AF93CFEA649172EDA7AC5E071E2D 3AF0BD", "Status": "Online", "TimeOfLastSuccessfulBackup": null, "UseFailoverUri": false, "UseServiceNet": true 5.3. Create a backup configuration Create a backup configuration in which you define the following basic items: The name of the backup What you want to back up When you want to back up How often you want to back up Look carefully at the Inclusions and Exclusions sections. Note that each exclusion must be within a folder that is included. If you like, you can programmatically create many configuration files like this with small changes for each server that you create. The HTTP request must include a header to specify the authentication token. The curl request uses the -s option for silent or quiet mode (no progress or error messages shown) and the -X option to specify the request operation to use when communicating with the HTTP server (instead of using the default operation). 14

20 If you have the tools, you can run the curl JSON request examples with the following option to format the output from curl: <curl JSON request example> python -m json.tool. An HTTP status code of 200 (OK) in the response indicates that the request succeeded. Example 5.3. Create a backup configuration curl -s -X POST backup-configuration \ -H "X-Auth-Token: yourauthtoken" \ -H "Content-Type: application/json" \ -d ' "MachineAgentId": , "BackupConfigurationName": "Weekly Website Backup", "IsActive": true, "VersionRetention": 30, "MissedBackupActionId": 1, "Frequency": "Weekly", "StartTimeHour": 7, "StartTimeMinute": 30, "StartTimeAmPm": "PM", "DayOfWeekId": 5, "HourInterval": null, "TimeZoneId": "Eastern Standard Time", "NotifyRecipients": "test@my- -address.com", "NotifySuccess": true, "NotifyFailure": true, "Inclusions": [ "FilePath": "C:\\backup_up_file.txt", "FileItemType": "File", "FilePath": "C:\\backed_up_folder", "FileItemType": "Folder" ], "Exclusions": [ "FilePath": "C:\\backed_up_folder\\excluded_file.txt", "FileItemType": "File" ] ' python -m json.tool "BackupConfigurationId": , "BackupConfigurationName": "Weekly Website Backup", "BackupConfigurationScheduleId": , "BackupPostscript": "", "BackupPrescript": "", "Datacenter": "DFW", "DayOfWeekId": 5, "EncryptionKey": "ExponentHex": 10001, 15

21 "ModulusHex": "C6054E90E32D2B25E16F3A560E1B4DC580B1E4AB74E0C DD8A1BD F6A526B16C55225D1BE6E0B1265F4085FB2F61B61337F5D32198E5CAFFEA CD50E90517A329146E43B20194C082A9C890060AD07A542FBC035B2A96F9F212C6D94887BECB 5E15F3E55397B975B1896CFC66EBB5DD7D A0E7F669ADB925A7BE4C1ECED1BC9E92DB 768CE76FDC86CCDD04BDF469679FE3261AA66C22AC6263E540B79780AAF09CFC798CDC4D EA4BD1BF511E4881E07C5387DDDBE741E615ACA0C32A738F5B952F1C17051EC3BAF 9F64C629515EA2AF93E6BB450A8B1B3E D5670AF93CFEA649172EDA7AC5E071E2D 3AF0BD", "Exclusions": [ "FileId": , "FileItemType": "File", "FilePath": "C:\\backed_up_folder\\excluded_file.txt", "FilePathEncoded": null, "Filter": "Exclude", "ParentId": ], "Flavor": "RaxCloudServer", "Frequency": "Weekly", "HourInterval": null, "Inclusions": [ "FileId": , "FileItemType": "File", "FilePath": "C:\\backup_up_file.txt", "FilePathEncoded": null, "Filter": "Include", "ParentId": , "FileId": , "FileItemType": "Folder", "FilePath": "C:\\backed_up_folder", "FilePathEncoded": null, "Filter": "Include", "ParentId": ], "IsActive": true, "IsDeleted": false, "IsEncrypted": false, "LastRunBackupReportId": null, "LastRunTime": null, "MachineAgentId": , "MachineName": "web2", "MissedBackupActionId": 1, "NextScheduledRunTime": "/Date( )/", "NotifyFailure": true, "NotifyRecipients": "test@my- -address.com", "NotifySuccess": true, "StartTimeAmPm": "PM", "StartTimeHour": 11, "StartTimeMinute": 30, "TimeZoneId": "Eastern Standard Time", "VersionRetention": 30 16

22 5.4. List all backup configurations for an agent To verify that your backup configuration exists, you can list all of the backup configurations for your agent. The output is similar to that in Section 5.3, Create a backup configuration [14]. The HTTP request must include a header to specify the authentication token. The curl request uses the -s option for silent or quiet mode (no progress or error messages shown) and the -X option to specify the request operation to use when communicating with the HTTP server (instead of using the default operation). If you have the tools, you can run the curl JSON request examples with the following option to format the output from curl: <curl JSON request example> python -m json.tool. An HTTP status code of 200 (OK) in the response indicates that the request succeeded. Example 5.4. List all backup configurations for an agent curl -s -X GET backup-configuration/system/youmachineagentid \ -H "X-Auth-Token: yourauthtoken" python -m json.tool [ "BackupConfigurationId": , "BackupConfigurationName": "Weekly Website Backup", "BackupConfigurationScheduleId": , "BackupPostscript": "", "BackupPrescript": "", "Datacenter": "DFW", "DayOfWeekId": 5, "EncryptionKey": "ExponentHex": 10001, "ModulusHex": "C6054E90E32D2B25E16F3A560E1B4DC580B1E4AB74E0C DD8A1BD F6A526B16C55225D1BE6E0B1265F4085FB2F61B61337F5D32198E5CAFFEA CD50E90517A329146E43B20194C082A9C890060AD07A542FBC035B2A96F9F212C6D94887BECB 5E15F3E55397B975B1896CFC66EBB5DD7D A0E7F669ADB925A7BE4C1ECED1BC9E92DB 768CE76FDC86CCDD04BDF469679FE3261AA66C22AC6263E540B79780AAF09CFC798CDC4D EA4BD1BF511E4881E07C5387DDDBE741E615ACA0C32A738F5B952F1C17051EC3BAF 9F64C629515EA2AF93E6BB450A8B1B3E D5670AF93CFEA649172EDA7AC5E071E2D 3AF0BD", "Exclusions": [ "FileId": , "FileItemType": "File", "FilePath": "C:\\backed_up_folder\\excluded_file.txt", "FilePathEncoded": null, "Filter": "Exclude", "ParentId": ], "Flavor": "RaxCloudServer", 17

23 ] "Frequency": "Weekly", "HourInterval": null, "Inclusions": [ "FileId": , "FileItemType": "File", "FilePath": "C:\\backup_up_file.txt", "FilePathEncoded": null, "Filter": "Include", "ParentId": , "FileId": , "FileItemType": "Folder", "FilePath": "C:\\backed_up_folder", "FilePathEncoded": null, "Filter": "Include", "ParentId": ], "IsActive": true, "IsDeleted": false, "IsEncrypted": false, "LastRunBackupReportId": null, "LastRunTime": null, "MachineAgentId": , "MachineName": "web2", "MissedBackupActionId": 1, "NextScheduledRunTime": "/Date( )/", "NotifyFailure": true, "NotifyRecipients": "test@my- -address.com", "NotifySuccess": true, "StartTimeAmPm": "PM", "StartTimeHour": 11, "StartTimeMinute": 30, "TimeZoneId": "Eastern Standard Time", "VersionRetention": Update a backup configuration To schedule the backup for one hour later, for example, you can update the backup configuration that you created earlier. Specify the BackupConfigurationId value in the URI. Send the same JSON content that you used in Section 5.3, Create a backup configuration [14] but make the following changes: Add v2 to BackupConfigurationName. Change StartTimeHour to 8. The HTTP request must include a header to specify the authentication token. The curl request uses the -s option for silent or quiet mode (no progress or error messages shown) and the -X option to specify the request operation to use when communicating with the HTTP server (instead of using the default operation). 18

24 If you have the tools, you can run the curl JSON request examples with the following option to format the output from curl: <curl JSON request example> python -m json.tool. This operation does not return a response body. An HTTP status code of 200 (OK) in the response indicates that the request succeeded. Example 5.5. Update a backup configuration curl -i -X PUT backup-configuration/yourbackupconfigurationid \ -H "X-Auth-Token: yourauthtoken" \ -H "Content-Type: application/json" \ -d ' "MachineAgentId": , "BackupConfigurationName": "Weekly Website Backup v2", "IsActive": true, "VersionRetention": 30, "MissedBackupActionId": 1, "Frequency": "Weekly", "StartTimeHour": 8, "StartTimeMinute": 30, "StartTimeAmPm": "PM", "DayOfWeekId": 5, "HourInterval": null, "TimeZoneId": "Eastern Standard Time", "NotifyRecipients": "test@my- -address.com", "NotifySuccess": true, "NotifyFailure": true, "Inclusions": [ "FilePath": "C:\\backup_up_file.txt", "FileItemType": "File", "FilePath": "C:\\backed_up_folder", "FileItemType": "Folder" ], "Exclusions": [ "FilePath": "C:\\backed_up_folder\\excluded_file.txt", "FileItemType": "File" ] ' python -m json.tool You can verify that the configuration is updated by using the following curl request, specifying the same BackupConfigurationId that you used in the update request. curl -s -X GET backup-configuration/yourbackupconfigurationid \ -H "X-Auth-Token: yourauthtoken" python -m 5.6. Start a backup manually If you do not do anything, Cloud Backup runs the backup at the scheduled time. 19

25 If you want to run the backup once to ensure that it works, you can start the backup manually. Use the BackupConfigurationId to indicate the backup configuration that you want to run. You can run the backup job as many time as you like. A backup is created each time you run the job. The HTTP request must include a header to specify the authentication token. The curl request uses the -i option to send the HTTP response to terminal output and the -X option to specify the correct HTTP method. This operation does not return a response body. An HTTP status code of 200 (OK) in the response indicates that the request succeeded. Example 5.6. Start a backup manually curl -i -X POST backup/action-requested \ -H "X-Auth-Token: yourauthtoken" \ -H "Content-Type: application/json" \ -d ' "Action" : "StartManual", "Id": yourbackupconfigurationid ' The response comes from the server. The number at the end of the response is the ID of the job. HTTP/ OK... Date: Thu, 31 Jul :54:38 GMT When the backup is done, you receive an about the status, as shown in the following example. Receiving the is based on the NotifyRecipients, NotifySuccess, and NotifyFailure parameters that you specify when you create your backup configuration (see Section 5.3, Create a backup configuration [14]). Rackspace Cloud Backup Backed Up: Weekly Website Backup v2 on web2 Status: Completed Started: 31 Jul :54 UTC Completed: 31 Jul :54 UTC Source: web02 Files Searched: 2 (4 KB) Errors Encountered: Checking backup status You can verify whether your backup jobs ran properly, and if they did not, what errors occurred. The HTTP request must include a header to specify the authentication token. 20

26 The curl request uses the -s option for silent or quiet mode (no progress or error messages shown) and the -X option to specify the request operation to use when communicating with the HTTP server (instead of using the default operation). If you have the tools, you can run the curl JSON request examples with the following option to format the output from curl: <curl JSON request example> python -m json.tool. The following example output shows "CurrentState": "Queued". Other valid values for CurrentState are as follows: Completed CompletedWithErrors Failed InProgress Missed Preparing Skipped StartRequested StartScheduled Stopped StopRequested An HTTP status code of 200 (OK) in the response indicates that the request succeeded. Example 5.7. Checking backup status curl -s -X GET backup/yourbackupid \ -H "X-Auth-Token: yourauthtoken" \ -H "Content-Type: application/json python -m json.tool "BackupId": , "BackupConfigurationId": , "CurrentState": "Queued", "BackupConfigurationName": "Weekly Website Backup v2", "MachineAgentId": , "MachineName": "web2", "StateChangeTime": "/Date( )/", "IsEncrypted": false, "EncryptionKey": "ExponentHex": 10001, "ModulusHex": "C6054E90E32D2B25E16F3A560E1B4DC580B1E4AB74E0C DD8A1BD F6A526B16C55225D1BE6E0B1265F4085FB2F61B61337F5D32198E5CAFFEA CD50E90517A329146E43B20194C082A9C890060AD07A542FBC035B2A96F9F212C6D94887BECB 21

27 5E15F3E55397B975B1896CFC66EBB5DD7D A0E7F669ADB925A7BE4C1ECED1BC9E92DB 768CE76FDC86CCDD04BDF469679FE3261AA66C22AC6263E540B79780AAF09CFC798CDC4D EA4BD1BF511E4881E07C5387DDDBE741E615ACA0C32A738F5B952F1C17051EC3BAF 9F64C629515EA2AF93E6BB450A8B1B3E D5670AF93CFEA649172EDA7AC5E071E2D 3AF0BD" 5.8. List activity for an agent You can display all the activities for an agent to find out whether your backups ran successfully or failed. This operation is useful if you do not set notifications when you create your backup configuration (see Backup configuration [29]) and want to create a report about the state of previous backups. The operation lists all in-progress and completed activity for an agent. Activity types are Backup, Cleanup, and Restore. The HTTP request must include a header to specify the authentication token. The curl request uses the -s option for silent or quiet mode (no progress or error messages shown) and the -X option to specify the request operation to use when communicating with the HTTP server (instead of using the default operation). If you have the tools, you can run the curl JSON request examples with the following option to format the output from curl: <curl JSON request example> python -m json.tool. An HTTP status code of 200 (OK) in the response indicates that the request succeeded. Example 5.8. List activity for an agent curl -s -X GET system/activity/youragentid / -H "X-Auth-Token: yourauthtoken" \ -H "Content-Type: application/json" python -m json.tool [, "CurrentState": "Completed", "DestinationDatacenter": "", "DestinationMachineAgentId": 0, "DestinationMachineName": "", "DisplayName": "Cleanup", "ID": , "IsBackupConfigurationDeleted": false, "ParentId": 0, "SourceDatacenter": "DFW", "SourceMachineAgentId": , "SourceMachineName": "web2", "TimeOfActivity": "/Date( )/", "Type": "Cleanup" "CurrentState": "Completed", "DestinationDatacenter": "", "DestinationMachineAgentId": 0, 22

28 ] "DestinationMachineName": "", "DisplayName": "Web2", "ID": , "IsBackupConfigurationDeleted": true, "ParentId": 54020, "SourceDatacenter": "DFW", "SourceMachineAgentId": , "SourceMachineName": "web2", "TimeOfActivity": "/Date( )/", "Type": "Backup" 5.9. Create a restore configuration Now that you have a backup, you can restore it to a different location on your server. You can also restore it to a different server, or to the same folder on the same server. You must set the BackupMachineId, DestinationMachineId, and DestinationPath values properly. BackupId identifies the backup that you want to use to restore. The HTTP request must include a header to specify the authentication token. The curl request uses the -s option for silent or quiet mode (no progress or error messages shown) and the -X option to specify the request operation to use when communicating with the HTTP server (instead of using the default operation). If you have the tools, you can run the curl JSON request examples with the following option to format the output from curl: <curl JSON request example> python -m json.tool. An HTTP status code of 200 (OK) in the response indicates that the request succeeded. Example 5.9. Create a restore configuration curl -s -X PUT restore / -H "X-Auth-Token: yourauthtoken" \ -H "Content-Type: application/json" \ -d ' "BackupId": , "BackupMachineId": , "DestinationMachineId": , "DestinationPath": "C:\\FolderPathForRestore\\", "OverwriteFiles": false ' python -m json.tool "RestoreId": 1394, "BackupId": , "DestinationMachineId": , "OverwriteFiles": false, "BackupConfigurationId": , "BackupConfigurationName": "Weekly Website Backup v2", "BackupRestorePoint": "\Date( )\", "BackupMachineId": , "BackupMachineName": "TestWindows1", "BackupFlavor": "RaxCloudServer", 23

29 "DestinationMachineName": "TestWindows2", "DestinationPath": "C:\\FolderPathForRestore\\", "IsEncrypted": false, "EncryptedPassword": null, "PublicKey": "ExponentHex": 10001, "ModulusHex": "C6054E90E32D2B25E16F3A560E1B4DC580B1E4AB74E0C DD8A1BD F6A526B16C55225D1BE6E0B1265F4085FB2F61B61337F5D32198E5CAFFEA CD50E90517A329146E43B20194C082A9C890060AD07A542FBC035B2A96F9F212C6D94887BECB 5E15F3E55397B975B1896CFC66EBB5DD7D A0E7F669ADB925A7BE4C1ECED1BC9E92DB 768CE76FDC86CCDD04BDF469679FE3261AA66C22AC6263E540B79780AAF09CFC798CDC4D EA4BD1BF511E4881E07C5387DDDBE741E615ACA0C32A738F5B952F1C17051EC3BAF 9F64C629515EA2AF93E6BB450A8B1B3E D5670AF93CFEA649172EDA7AC5E071E2D 3AF0BD", "RestoreStateId": Start a restore operation manually You can manually run a restore operation that is based on a restore configuration. Use the RestoreId that was returned in Section 5.9, Create a restore configuration [23]. The following example is for an unencrypted restore operation. For an encrypted restore operation, you add the EncryptedPassword parameter with its value. The HTTP request must include a header to specify the authentication token. The curl request uses the -s option for silent or quiet mode (no progress or error messages shown) and the -X option to specify the request operation to use when communicating with the HTTP server (instead of using the default operation). This operation does not return a response body. An HTTP status code of 204 (No Content) in the response indicates that the request succeeded. Example Start a restore manually curl -s -X POST https: //dfw.backup.api.rackspacecloud.com/v1.0/youraccountid/ restore/action-requested \ -H "X-Auth-Token: yourauthtoken" \ -H "Content-Type: application/json" \ -d '"Action": "StartManual", "Id": 1394 ' When the restore is complete, you receive an about the status, as shown in the following example. Receiving the is based on the NotifyRecipients, NotifySuccess, and NotifyFailure parameters that you specify when you create your backup configuration (see Section 5.3, Create a backup configuration [14]). Rackspace Cloud Backup Status: Completed Started: 01 Aug :40 UTC Completed: 01 Aug :40 UTC Destination: C:\\FolderPathForRestore\\ Files Restored: 2 (4 KB) Errors Encountered: 0 24

30 5.11. Get a restore report You can request a restore report that provides information about the restore operation and tells you if the operation ran successfully. The HTTP request must include a header to specify the authentication token. The curl request uses the -s option for silent or quiet mode (no progress or error messages shown) and the -X option to specify the request operation to use when communicating with the HTTP server (instead of using the default operation). If you have the tools, you can run the curl JSON request examples with the following option to format the output from curl: <curl JSON request example> python -m json.tool. An HTTP status code of 200 (OK) in the response indicates that the request succeeded. Example Get a restore report curl -s -X GET restore/report/yourrestoreid \ -H "X-Auth-Token: yourauthtoken" \ -H "Content-Type: application/json" python -m json.tool "BackupConfigurationId": , "BackupConfigurationName": "Weekly Website Backup v2", "BackupReportId": , "CompletedTime": "/Date( )/", "Diagnostics": "No errors", "Duration": "00:00:00", "ErrorList": [], "NumBytesRestored": "4 MB", "NumErrors": "0", "NumFilesRestored": "2", "OriginatingComputerName": "web02", "Reason": "Success", "RestoreDestination": "TestWindows2", "RestoreDestinationMachineId": , "RestorePoint": "/Date( )/", "StartTime": "/Date( )/", "State": "Completed" Cloud Backup reports success. You can also check the folder listings on your server Delete a backup configuration You can delete the backup configuration file and verify that it was removed. Note Similarly, you can also delete a restore configuration by using the operation to delete a restore configuration. 25

31 The HTTP request must include a header to specify the authentication token. The curl request uses the -i option to send the HTTP response to terminal output and the -X option to specify the correct HTTP method. This operation does not return a response body. An HTTP status code of 200 (OK) in the response indicates that the request succeeded. Example Delete a backup configuration curl -i -X DELETE 0/yourAccountID/backup-configuration/yourBackupConfigurationID \ -H "X-Auth-Token: yourauthtoken" To verify that the backup configuration is deleted, list the backup configuration details to see IsDeleted: True. Example List backup configuration details curl -s -X GET backup-configuration/yourbackupconfigurationid \ -H "X-Auth-Token: yourauthtoken" python -m json.tool "BackupConfigurationId": , "BackupConfigurationName": "Weekly Website Backup v2",... "IsDeleted": true,... 26

32 6. Additional resources For information about all Cloud Backup API operations, see the Rackspace Cloud Backup Developer Guide at All you need to get started with the Cloud Backup API is in this getting started guide, the developer guide, and your Rackspace Cloud account. For additional information about Cloud Backup, see the Knowledge Center, and especially, the Knowledge Center article Best Practices for Cloud Backup. The official support channels (phone, chat, , forums, and knowledge base articles) for Cloud Backup are available through the Rackspace Cloud website at Rackspace welcomes feedback, comments, and bug reports at If the Cloud Backup system is not functioning to your expectations, you can review the system status page at This page is updated to reflect up-to-date information about the system s current health and status. Visit the Product Feedback Forum and tell us what you think about Cloud Backup. You can follow Rackspace updates and announcements via Twitter at This API uses standard HTTP 1.1 response codes as documented at 27

33 7. Document change history This version of the guide replaces and obsoletes all earlier versions. The most recent changes are described in the following table: Revision Date March 18, 2015 March 4, 2015 January 14, 2015 August 12, 2014 Summary of Changes Corrected the curl example in Section 5.6, Start a backup manually [19] by changing action-request to action-requested at the end of the endpoint. Removed the London endpoint, since Rackspace now has one global endpoint for authentication using the Rackspace Cloud Identity service. See Chapter 4, Generate an authentication token [7]. Added a note that includes a link to additional authentication methods, including multi-factor authentication, in Chapter 4, Generate an authentication token [7]. Initial publishing of this guide. 28

34 Glossary Agent The application that is installed on the server that knows how to perform backups and restores. Backup A group of folders, files, or both stored on Cloud Backup for a particular server and configuration. Backup configuration The definition of what is going to be backed up and when. Restore The process of bringing your system back to a previously saved state. Restore configuration The definition of what is going to be restored and where. 29