The information in this section is relevant to all operations of the API. For details about specific operations, see the API reference.
The Rackspace Cloud Backup API is implemented using a RESTful web service interface. Like other Rackspace Cloud services, this service shares a common token-based authentication system that allows seamless access between products and services.
Note :All requests to authenticate against and operate the service are performed using SSL over HTTP (HTTPS) on TCP port 443. For authentication instructions, see Authenticate to the Rackspace Cloud.
Service access endpoints
The Rackspace Cloud Backup API service is a regionalized service. It allows the caller to select the region into which a load balancer is provisioned.
The following table lists the Rackspace Cloud Backup endpoints that are available for each region.
Tip :To help you decide which regionalized endpoint to use, read about special considerations for choosing a region.
Regionalized service endpoints
| Region | Endpoint |
|---|---|
| Dallas/Ft. Worth (DFW) | https://dfw.backup.api.rackspacecloud.com/v1.0/123456/ |
| Chicago (ORD) | https://ord.backup.api.rackspacecloud.com/v1.0/123456/ |
| London (LON) | https://lon.backup.api.rackspacecloud.com/v1.0/123456/ |
| Hong Kong (HKG) | https://hkg.backup.api.rackspacecloud.com/v1.0/123456/ |
| Northern Virginia (IAD) | https://iad.backup.api.rackspacecloud.com/v1.0/123456/ |
| Sydney (SYD) | https://syd.backup.api.rackspacecloud.com/v1.0/123456/ |
Replace the sample account ID number (which is also called the tenant ID), 123456, with your actual account number that is returned as part of the authentication response. The account number is located after the final slash (/) in the publicURL field.
The service catalog returned in the authentication response specifies the correct service access endpoint for your account to use for accessing Rackspace Cloud Backup. Use the service type (rax:backup) to locate the correct endpoint in the service catalog. For an example of the service catalog, see authentication response example.
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.
Service version
The Rackspace Cloud Backup version defines the contract and build information for the API.
Contract version
The contract version denotes the data model and behavior that the API supports. The contract version is included in all request URIs. Different contract versions of the API might be available at any given time and are not guaranteed to be compatible with one another.
Example request URI
https://dfw.backup.api.rackspacecloud.com/v1.0/1234/
List API version
You can list which API versions are available for your account by using the list versions request.
Issue a GET request to the root endpoint for a service. In the request, truncate the version and everything to the right of it.
Example list versions request
GET HTTP/1.1
Host: https://dfw.backup.api.rackspacecloud.com/
This operation does not require a request body.
Normal Response Codes: 200, 203
Error Response Codes: 400, 413, 500, 503
Request and response types
The Rackspace Cloud Backup API supports only the JSON data serialization format.
The request format is specified using the Content-Type: application/json header and is required for operations that have a request body.
You can specify the response format in requests by using the Accept header or by adding a .json extension to the request URI. If no response format is specified, JSON is the default.
Response formats
| Format | Accept header | Query extension | Default |
|---|---|---|---|
| JSON | application/json | .json | Yes |
Limits
All accounts, by default, have a preconfigured set of thresholds, or limits, to manage capacity and prevent abuse of the system.
The following table lists the limits for Cloud Backup.
Table: Limits for Cloud Backup
| Name | Description |
|---|---|
| Maximum number of backup configurations per agent | The number of backup configurations per agent is limited only by the maximum JSON document size for the agent configuration. (The agent configuration contains all of the configuration information specific to an agent.) Currently, the maximum JSON document size is 1 MB for the total document. |
| Maximum number of exclusions and inclusions per backup configuration | The maximum number of exclusions and inclusions per backup configuration is limited only by the maximum JSON document size for the agent configuration. (The agent configuration contains all of the configuration information specific to an agent.) Currently, the maximum JSON document size is 1 MB for the total document. |
| Maximum length of file paths in the configuration | The maximum length of file paths in the configuration is limited first by the maximum JSON document size of the agent configuration (see the preceding limit) and then by the operating system (OS) limitations. See the documentation for your OS for the exact maximum size of file paths on your OS. |
| Maximum backup upload speeds | The maximum upload speed of a backup is currently 2 MB per second but that speed depends on multiple factors including Cloud Files server load, network bandwidth, number of CPUs, noisy neighbors, duplicate blocks, and similar items. These factors can reduce the upload speed of a backup by varying amounts. However, duplicate or existing blocks actually increase the speed because uploads are not necessary for those blocks. |
| CPU usage limits | During an operation like a backup or restore, CPU usage limits are 95 percent by default. |
| Simultaneous uploads | Simultaneous uploads are based on available CPUs. If a server has one or two CPUs, the agent uses one CPU for its work. If a server has three or four CPUs, the agent uses two CPUs. If a server has five or six CPUs, the agent uses three CPUs. If the server has more than six CPUs, the agent uses no more than four CPUs. |
| Disk space limits for the cache drive | The disk space of the cache drive is where the agent stores log and database files, as well as temporary files. Currently, if this drive has less than 100 MB free space, Cloud Backup throttles logging and posts a message to the logs. Currently, the total size of the rollover logs is set to 10 files at 500 MB by default, but you can edit the log4cxx.xml file to change this value on a per-machine basis. |
| Really Simple Events (RSE) throttling levels | RSE communicates with the agent. RSE throttling levels control the traffic to RSE and are defined based on the state of the agent: Idle—once every 30 seconds, Active—once every 2 seconds, and Realtime— continuous. |
Response codes
Cloud Backup returns an HTTP code that denotes the type of response.
- Successful response codes are returned only if all configured providers were successful in processing the request.
- When an error occurs, the Rackspace Cloud Backup Service returns a fault object containing an HTTP error response code that denotes the type of error. In the body of the response, the system returns additional information about the fault.
This API uses standard HTTP 1.1 response codes.
The following table lists possible responses with their associated codes and descriptions.
Table: Response codes for Cloud Backup
| Response | Associated response code | Description |
| OK | 200 | The request has succeeded. |
| Created | 201 | The request has been fulfilled and a resource was created. |
| Accepted | 202 | The request has been accepted for processing. |
| No Content | 204 | The request has been fulfilled but does not return a representation (that is, the response is empty). |
| Bad Request | 400 | There was one or more errors in the user request. |
| Unauthorized | 401 | The supplied token is not authorized to access the resources, either it’s expired or invalid. |
| Forbidden | 403 | Access to the requested resource was denied. |
| Not Found | 404 | A requested resource was not found. |
| Instance Fault | 500 | This is a generic server error and the message contains the reason for the error. This error could wrap several error messages and is a catch all. |
| Not Implemented | 501 | The requested method or resource is not implemented. |
| Service Unavailable | 503 | The Rackspace Cloud Backup Service is not |
The symptoms and solutions for some frequently encountered issues follow.
Backups get corrupted
- Does your server have a backup agent and did you clone it to create a new backup system? This means that two backup agents exist with the same credentials writing to the same vault.
- Solution: Ensure the agent on the cloned backup server is re-registered before any backups are run.
Backups get network error
- Solution: Make sure that your backup server has a connection to both service net and public net. If it is on an isolated network, the backup agent is able to function properly.
Backups sometimes fail
- This is most commonly caused by either a failure to communicate with Cloud Files, running out of disk space, or a failure to communicate with Cloud Backup.
- Sometimes the agent might fail to backup a particular file because of a permissions error. Either the file is in use when the agent attempts to save it or the file in question cannot be read by the agent. Consider permissions when hunting for the root cause of a backup failure.
- Solution: Make sure that you’re running the latest agent release. After that, attempt to determine the cause of the error, and try the backup or restore again if it is an intermittent error.
Backup or Restore is slow
- If your backup or restore is encrypted, it can be especially slow. Encryption comes at a cost.
- If your system uses Cloud Block Storage as the storage medium, this is known to introduce some slowdowns. Consider whether the benefits of using Cloud Block Storage outweigh the need for faster backups/restores.
- Solution: Make sure that you’re running the latest agent release. After that, attempt to determine the cause of the error, and try the backup or restore again if it is an intermittent error. We’re always working on making backup more robust.
Role-based access control (RBAC)
Role-based access control (RBAC) restricts access to the capabilities of Rackspace Cloud services, including the Rackspace Cloud Backup API, to authorized users only. RBAC enables Rackspace Cloud customers to specify users have access to which Rackspace Cloud Backup API service capabilities, based on roles defined by Rackspace. The permissions to perform certain operations in Rackspace Cloud Backup API (create, read, update, delete) are assigned to specific roles. The account owner user assigns these roles, either global (multiproduct) or product-specific (for example, Rackspace Cloud Backup), to account users.
Assigning roles to account users
The account owner (identity:user-admin) can create account users on the account and then assign roles to those users. The roles grant the account users specific permissions for accessing the capabilities of the Rackspace Cloud Backup service. Each account has only one account owner, and that role is assigned by default to any Rackspace Cloud account when the account is created.
See the Identity API guide for information about how to perform the following tasks:
Note :The account owner (identity:user-admin) role cannot hold any additional roles because it already has full access to all capabilities.
Roles available for Rackspace Cloud Backup
The following table describes the roles that can be used to access the Rackspace Cloud Backup API.
| Role name | Role permissions |
|---|---|
| cloudbackup:admin | This role provides Create, Read, Update, and Delete permissions in Rackspace Cloud Backup, where access is granted. |
| cloudbackup:creator | This role provides Create, Read, and Update permissions in Rackspace Cloud Backup, where access is granted. |
| cloudbackup:observer | This role provides Read permission in Rackspace Cloud Backup, where access is granted. |
Multiproduct global roles and permissions
Additionally, two multiproduct roles apply to all products. Users with multiproduct roles inherit access to products when those products become RBAC-enabled. The following table describes these roles and their permissions.
Multiproduct roles and permissions
| Role name | Role permissions |
|---|---|
| admin | This role provides Create, Read, Update, and Delete permissions in all products, where access is granted. |
| observer | This role provides Read permission in all products, where access is granted. |
Resolving conflicts between RBAC multiproduct and product-specific roles
The account owner can set roles for both multiproduct and Rackspace Cloud Backup scope, and it is important to understand how any potential conflicts between these roles are resolved. When two roles appear to conflict, the role that provides the more extensive permissions takes precedence. Therefore, admin roles take precedence over observer and creator roles, because admin roles provide more permissions.
The following table shows two examples of how potential conflicts between user roles in the Control Panel are resolved.
| Permission configuration | Control Panel permission view | Control Panel admin capabilities |
|---|---|---|
| User is assigned the following roles: multiproduct observer and Rackspace Cloud Backup admin | Appears that the user has only the multiproduct observer role | User can perform admin functions for Rackspace Cloud Backup only. The user has the observer role for the rest of the products. |
| User is assigned to the following roles: multiproduct admin and Rackspace Cloud Backup observer | Appears that the user has only the multiprodcut admin role | User can perform admin functions for all of the products. The Rackspace Cloud Backup observer role is ignored. |
RBAC permissions cross-reference to Rackspace Cloud Backup API operations
API operations for Rackspace Cloud Backup may or may not be available to all roles. To see which operations are permitted to invoke which calls, review the Permissions Matrix for Role-Based Access Control (RBAC).