API & Client Libraries
Sections:
1-Minute Walkthrough
The API is REST-ful HTTPS with JSON. Here is a basic walkthrough using the tar and curl commands. See the Software page for other tools that work with RestBackup™.
-
Sign up and create a backup account. Copy the backup account's access url:
https://Y21R3P:Mj313x2D1OyrTSpy@us.restbackup.com/
Each access url has the formathttps://username:password@host/
- Back up your files to the access url
$ tar czf data.20100523.tar.gz file1 file2 $ curl -u Y21R3P:Mj313x2D1OyrTSpy https://us.restbackup.com/ -T data.20100523.tar.gz Stored /data.20100523.tar.gz
- List backups
$ curl -u Y21R3P:Mj313x2D1OyrTSpy https://us.restbackup.com/ [ {"name":"/data.20100521.tar.gz","size":396265,"createtime":1274439603}, {"name":"/data.20100522.tar.gz","size":416849,"createtime":1274526004}, {"name":"/data.20100523.tar.gz","size":530061,"createtime":1274612402} ]
- Restore your files
$ curl -u Y21R3P:Mj313x2D1OyrTSpy https://us.restbackup.com/data.20100523.tar.gz |tar xz
Client Libraries
- restbackup-java – Classes for using the Backup API
-
restbackup-python
- Classes for using the Backup API
- Classes for encrypting, verifying, and decrypting data streams
Backup API
The Backup API allows you to upload, download, and list files stored in a backup account.
Security
The API uses encryption (https) for privacy and security.
Every backup account has an access url composed of four parts: protocol, username, password, and host. Since the API is only available over encrypted connections, the protocol is always https.
- Example access url:
https://Y21R3P:Mj313x2D1OyrTSpy@us.restbackup.com/
- Protocol:
https
- Username:
Y21R3P
- Password:
Mj313x2D1OyrTSpy
- Host:
us.restbackup.com
Here is a regular expression for parsing access urls:
^https://([a-zA-Z0-9]+):([a-zA-Z0-9]+)@([-.a-zA-Z0-9]+(?::[0-9]+)?)/$
Use http basic authentication to identify the backup account.
Simply provide an Authorization header with "user:pass"
encoded in Base64:
Authorization: Basic WTIxUjNQOk1qMzEzeDJEMU95clRTcHk=
The Client Libraries provide encryption functions for an extra layer of security.
Backup
PUT /data.20100523.tar.gz HTTP/1.1
Use the HTTP PUT method to upload files to a backup account. Since this is a REST interface, the file will live at the path you specify. Retrieve it with an HTTP GET.
Your request must include a correct Content-Length header. The maximum file size is 5 GB, 5368709120 bytes.
You cannot replace existing files. PUTs to existing files will fail with "405 Method Not Allowed".
You can choose how long to keep the files. Go to Manage Accounts and configure the retention period for the backup account. You can specify that uploaded files are kept for 30 days to 1 year.
A "201 Created" response indicates that the file was received.
Restore
Use the HTTP GET verb to download files:
GET /data.20100522.tar.gz HTTP/1.1
Example:
$ curl -u Y21R3P:Mj313x2D1OyrTSpy https://us.restbackup.com/data.20100522.tar.gz >data.20100522.tar.gz
List
You can also list uploaded files:
GET / HTTP/1.1
Example:
$ curl -u Y21R3P:Mj313x2D1OyrTSpy https://us.restbackup.com/ [ {"name":"/data.20100521.tar.gz","size":396265,"createtime":1274439603}, {"name":"/data.20100522.tar.gz","size":416849,"createtime":1274526004}, {"name":"/data.20100523.tar.gz","size":530061,"createtime":1274612402} ]
The access url also works in your web browser. For Internet Explorer, first go to https://us.restbackup.com/, then enter the username and password from the access url.
Sessions
Some browsers do not support access urls when browsing or downloading. For these browsers, use the MAKESESSION command to get another URL that allows downloading.
Example request:
POST / HTTP/1.1 X-HTTP-Method-Override: MAKESESSION Authorization: Basic WTIxUjNQOk1qMzEzeDJEMU95clRTcHk= Host: us.restbackup.com
Example response:
HTTP/1.1 204 No Content Location: https://us.restbackup.com/session/G4c9Pf7kN73Sklc3/ Date: Wed, 14 Nov 2012 05:13:36 GMT
Navigate a browser to the URL returned in the Location header. The browser will show the list of backups available for download.
A session is valid for 24 hours. Requests to an expired session URL will return "410 Gone" with an explanation that the session expired.
Delete
The API currently does not allow deletes. Files are kept until they expire.
Other APIs
The Management API and Signup API are no longer supported.