REST API

UploadCare provides a RESTful API for dealing with your files and other operations. The API protocol and resources are described in this document.

API Protocol

UploadCare API is REST over HTTP. The base URI is http://api.uploadcare.com/.

Every request to API should be signed.

API supports different content types, including json and xml. You should use Content-Type header for indicating in which format you’d like to send or receive data.

You can play with API in your browser - just open any resource url, like http://api.uploadcare.com/files/ .

Authentication

To make a request to http://api.uploadcare.com/, you should sign it with your own public and private keys. This is done in several steps:

1. You generate a Date string in RFC 2822 format,

Fri, 09 Nov 2001 01:08:47 -0000

This can be done, for example, via standard Python library function: email.utils.formatdate(usegmt=True). The date should be within ~15 minutes of our server time at the time of your request.

2. This string you should send as an HTTP Date header with your request. You can use X-Uploadcare-Date if your software doesn’t support the usual header for some reason.
3. The “message” to sign is generated like this (Python):

'\n'.join([verb,         # an http verb, like 'GET' (uppercase)
           content_md5,  # an md5 hash of the request contents
                         # if you're sending empty request (for example, using GET), use md5('')
           content_type, # contents of your Content-Type header, like 'application/json'
           date,         # date from the step 1
           uri])         # request uri, like '/files/some-file-id/'

4. You generate a HMAC signature, with sha1 digest, of this string, using your secret key as a key.

import hmac
import hashlib

hmac.new(str(secret),
         sign_string,
         hashlib.sha1).hexdigest()

5. You send a special header, Authentication, in this format: 'UploadCare %s:%s' % (public_key, signature), with your request.

I’ve actually stolen this algorithm from S3 specification. Probably I’ve overengineered it a bit. I should think more.

You can take a look at the Python implementation.

File Resource

You can’t create files with this. Please use upload for that.

Collection URI: http://api.uploadcare.com/files/

• GET request to the collection URI returns a list of files.

Element URI: http://api.uploadcare.com/files/<file_id>/

• GET request to the element URI return information about a particular file.
• DELETE request schedules the file for deletion.
• POST request can be made to change the file state. Right now the only paramater supported is:
  • keep - set it to “1” to keep the file

In both cases (list and particular file), the file structure looks like this:

{
    "file_id": "d1675406-64aa-4bd5-8b89-7bcbafd10125",
    "last_keep_claim": "2012-05-04T05:26:57.886",
    "made_public": true,
    "mime_type": "image/jpeg",
    "on_s3": true,
    "original_file_url": "http://s3.amazonaws.com/uploadcare/d1675406-64aa-4bd5-8b89-7bcbafd10125/20120503211528.jpg",
    "original_filename": "20120503211528.jpg",
    "removed": null,
    "size": 177808,
    "upload_date": "2012-05-04T05:27:03.136",
    "url": "http://api.uploadcare.com/files/d1675406-64aa-4bd5-8b89-7bcbafd10125/"
}

Frequent Problems

Just a list of problems we’ve noticed to appear frequently:

1. All the urls end with slash. For example, http://api.uploadcare.com/files won’t work. It returns a redirect to the right path, but most client libraries will fail at this step, because for the different URI you’ll need a different signature (see step 3 of signing process).