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™.

  1. 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 format https://username:password@host/
  2. 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
  3. 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}
    ]
    
  4. Restore your files
    $ curl -u Y21R3P:Mj313x2D1OyrTSpy https://us.restbackup.com/data.20100523.tar.gz |tar xz

Client Libraries

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.

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.

Top of Page