Quick Start

You have several options to use UploadCare with your form.

Using AJAX widgets

We encourage you to use our file uploading widgets. To use them, you should add a special hidden field for your form, and give it a role: uploadcare-plain-uploader. For example:

<form action="/your/upload/handler/" method="POST">
    <p>Your name: <input name="username"></p>
    <p><input type="checkbox" name="robot" value="1"> I'm a robot</p>
    <p>Your photo: <input name="photo" type="hidden" role="uploadcare-plain-uploader"></p>
    <p><input type="submit"></p>
</form>

Available roles for widgets are upload-plain-uploader (bare bones) and upload-line-uploader (a beautiful one).

You’ll have to include a special script for these widgets to work.

For ‘plain’ widget:

<script src="http://static.uploadcare.com/assets/uploaders/plain-widget.js" data-public-key="YOUR_PUBLIC_KEY"></script>

For ‘line’ widget:

<script src="http://static.uploadcare.com/assets/uploaders/line-widget.en.js" data-public-key="YOUR_PUBLIC_KEY"></script>

And then you’re ready to go. As soon as the form is submitted, you’ll have a file id in the corresponding field (in the example, it’s photo).

Submit Uploader

You don’t have to use our widgets. Another option to make UploadCare receive files uploaded by one of your forms is changing this form’s action. UploadCare will save all files it gets and return the form to you (by showing it to the user again and quickly submitting it using JavaScript) - with files replaced by their IDs.

All you need to do is replace the action of your form, and add two hidden parameters, namely your UploadCare public key and the true receiver of your form, to which it will be submitted after receiving the files (you don’t have to use it if you’re using widgets! Just skip this section):

<form action="http://0.0.0.0:8000/upload/submit/" method="post" enctype="multipart/form-data">
  <input type="hidden" name="UPLOADCARE_ACTION" value="http://yourdomain.com/example1/" />
  <input type="hidden" name="UPLOADCARE_PUB_KEY" value="{{ UPLOADCARE_PUB_KEY }}" />

  <p>Your name: <input name="username"></p>
  <p><input type="checkbox" name="robot" value="1"> I'm a robot</p>
  <p>Your photo: <input name="photo" type="file"></p>
  <p><input type="submit"></p>
</form>

Make sure the url in “UPLOADCARE_ACTION” is absolute!

Handling files on your server

Now you have this form for uploading files and other stuff. If you submit it, that’s the data your server software is going to receive:

POST: <QueryDict: {u'username': [u'd'], u'photo': [u'584f2f49-e3e7-439d-8657-629dd0cd9524'], u'robot': [u'1']}>
FILES: <MultiValueDict: {}>

As you can see, the file was taken by UploadCare, and you was given its id.

Although the file is stored now somewhere on the internets, it probably won’t last long. To prevent it from deletion, you should ask UploadCare to keep it. It can be done by the API call.

Keeping a file

If you don’t need an uploaded file, you don’t have to do anything - it will be deleted . But to store it forever (or until you decide to get rid of it), you should tell UploadCare to keep it.

It’s done by a simple POST request to the file RESTful URI (http://api.uploadcare.com/files/{{ file_id }}/) with only one POST parameter: keep=1. Consult section about API about making and signing such requests.

If you’re using the Python library, there is a function for that.

Making an API request

To make a request to http://api.uploadcare.com/, you should sign it. 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 also use X-Uploadcare-Date, if you want.
3. You create a string like this:

'\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,         # a 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.