API Documentation

Description

Upload images to a Shutterfly album.

Call Signature

Application ID and call signature are required. Please see Call Signature documentation for more details.

Resource Path

This API uses the following resource path element:

/images

Methods

POST - Stores an image at Shutterfly.

Scheme

http
https (optional)

Host

up3.shutterfly.com

Method Endpoint example

POST http://up3.shutterfly.com/images

Method	Endpoint example

POST	http://up3.shutterfly.com/images

In the following Method detail sections, click on Method name to expand or collapse the detail.

Method: POST

Stores an image at Shutterfly.

Note that the real endpoint, i.e., the Shutterfly album being uploaded to (and optionally the folder), is expressed as a POST form parameter.

Sample Input

POST /images?oflyAppId=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: up3.shutterfly.com
Content-Type: multipart/form-data; boundary=AaB03x
Content-Length: xxxxxx

--AaB03x
Content-Disposition: form-data; name="AuthenticationID"

000020654580|1196723290244|f248719765da1c300387b49e83faadfe23f76c63
--AaB03x
Content-Disposition: form-data; name="Image.AlbumName"

My first album
--AaB03x
Content-Disposition: form-data; name="Image.Data"; filename="sphinx.jpg"
Content-Type: image/jpeg

[... first image's binary data ...]
--AaB03x
Content-Disposition: form-data; name="Image.Data"; filename="parthenon.jpg"
Content-Type: image/jpeg

[... next image's binary data ...]
--AaB03x--

Input Parameters

Content-Type

multipart/form-data; boundary=--------xxxxxx

Submit the following parameters in the Post body as multi-part form data.

AuthenticationID

A 'Content-Disposition: form-data' part for the User Authentication token, obtained from the User Authentication API.

This parameter is optional if the user has granted permission to your app with Seamless Sign-in, in which case you would pass a user token as described in its documentation.

Count: 0 - 1

Example: 000020654580|1195595728543|7b0df350319ce49be36aa52b038f8949ac285bdf

Image.AlbumName

A 'Content-Disposition: form-data' part for the name of the user album that the images should be uploaded to. If the album does not exist, it will be created. If not specified, a default album name of today's date will be used.

Count: 0 - 1

Length: 1 - 80

Example: My first album

Image.FolderName

A 'Content-Disposition: form-data' part for the name of the user folder that the target album should reside in. If the folder does not exist, it will be created. If not specified, the user's default folder will be used (usually named "My Albums"). If the target album does not exist within that folder, a new album will be created.

Count: 0 - 1

Length: 1 - 80

Example: My first folder

Image.Data

A 'Content-Disposition: form-data' part for the image being uploaded to Shutterfly, including its filename, Content-Type and binary contents. JPEG is the only supported format, so Content-Type should always be "image/jpeg". As indicated, this part can repeat to batch-upload multiple images. All images go into the same album.

Count: 1 - 10

Length: 0 - 20 Mb each

Example: (image data)

filename

A sub-parameter of Image.Data, giving a filename for the image being uploaded. See the Sample Invocation.

Count: 1

Example: filename="C:\pictures\sphinx.jpg"

Sample Output

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:sflymedia="http://media.openfly.shutterfly.com/v1.0" 
	xmlns:upload="http://upload.openfly.shutterfly.com/v1.0" xmlns:dc="http://purl.org/dc/elements/1.1/" 
	xmlns:media="http://search.yahoo.com/mrss/" xmlns:openfly="http://openfly.shutterfly.com/v1.0">
  <title>Upload Result</title>
  <link rel="related" href="http://ws.shutterfly.com/albumid/67b0de21e8f56794f4fd"/>
  <category term="upload-result" scheme="http://upload.openfly.shutterfly.com/v1.0" />
  <upload:errCode>4</upload:errCode>
  <upload:errMessage>Invalid image format</upload:errMessage>
  <upload:numSuccess>1</upload:numSuccess>
  <upload:numFail>1</upload:numFail>
  <entry>
    <title>parthenon.jpeg</title>
    <link rel="alternate" type="text/html" 
        href="http://im1.shutterfly.com/procserv/47b7cf01b3127cce98504699e6e500000013109BcNWjVsyg" />
    <category term="image" scheme="http://media.openfly.shutterfly.com/v1.0" />
    <author>
      <name />
    </author>
    <id>47b7cf01b3127cce98504699e6e500000013109BcNWjVsyg</id>
    <updated>2007-11-20T08:00:00Z</updated>
    <published>2007-11-20T08:00:00Z</published>
    <content type="image/jpeg">
      http://im1.shutterfly.com/procserv/47b7cf01b3127cce98504699e6e500000013109BcNWjVsyg
    </content>
    <summary>parthenon.jpeg 2007-11-20</summary>
    <dc:date>2008-04-24T18:56:31Z</dc:date>
    <openfly:userid>9BcNWjVsyg</openfly:userid>
    <sflymedia:mediaid>47b7cf01b3127cce98504699e6e500000013109BcNWjVsyg</sflymedia:mediaid>
    <media:group>
      <media:content height="96" type="image/jpeg" width="64" 
          url="http://im1.shutterfly.com/proctaserv/47b7cf01b3127cce98504699e6e500000011109BcNWjVsyg" />
      <media:content height="1600" type="image/jpeg" width="1067" 
          url="http://im1.shutterfly.com/proctaserv/47b7cf01b3127cce98504699e6e500000013109BcNWjVsyg" />
      <media:category scheme="http://media.openfly.shutterfly.com/v1.0">lowResFullyEnhanced</media:category>
    </media:group>
  </entry>
  <entry>
    <title>Failed - plogo.png.jpg</title>
    <category term="upload-result" scheme="http://upload.openfly.shutterfly.com/v1.0" />
    <author>
      <name />
    </author>
    <upload:failedFileName>plogo.png.jpg</upload:failedFileName>
  </entry>
</feed>

Output Feed

Content-Type

application/atom+xml

feed

HTTP 200 (OK) is the normal response, even if images fail. The response will be Atom XML representing the result of the upload.

At the feed level, you will find elements describing the success/failure of the upload as a whole. If any image was successful, you will find the URL of the album that the image(s) uploaded to.

Each entry will represent an image that you tried to upload. Successfully uploaded images will be grouped first, in the order you posted them, followed by unsuccessful images (if any - and again, in the order you posted them).

upload-result entry

Error Codes

If there is no error, methods return HTTP status code 200 (or 201 for a create operation). See the documentation for Common Response Codes.

This API will return an HTTP 200 even in the case of image error. One of the following codes will be embedded in the <upload:errCode> and <upload:errMessage> elements of the returned XML feed.

0: OK

1: Invalid auth ID

2: Auth ID missing

3: Unexpected exception

4: Invalid image format

5: Album exception

6: Invalid image ID

7: Invalid offset

8: File append exception

9: Invalid state exception

10: IO exception

11: Archive exception

12: Source View creation exception

13: No image data

14: Already archived

15: NA

16: Missing parameter

API Explorer

To see this call in action, use the API explorer.

Frequently Asked Questions

General

What format should I use for the image contents?

Plain binary. Read the image file bytes and add them to your multipart/form-data stream "as they are". Do not encode them. Do not transform them.

The API lets me upload multiple files in one call. What is the advantage of doing that?

Each call you make over the Internet has associated overhead. An app that uploads more files in fewer calls will save some of that overhead. But with large images, the advantage is reduced, because the overhead is smaller than the time spent in actual image data transfer. It is OK with Shutterfly if you prefer to upload only one image per call.

What are the limits on how much my app can upload?

Up to 10 images per call, and up to 20 megabytes per image.

User Authentication

How does your upload API change, if my end user has Seamless Sign-in?

It doesn't change much. Omit the AuthenticationID parameter, but add "oflyUserid=[the SSI user token]" to the URL. The latter is described in the App Authentication documentation.

API errors

My upload doesn't work. It gets strange exceptions, like "IOException caught reading the stream". What's wrong?

POST multipart/form-data is not easy to program correctly. You must follow RFC1867 very exactly. Shutterfly recommends that you find a library routine in your programming language to do the job for you, or that you use the API Explorer to see what Shutterfly's library would generate.

My upload still doesn't work. Could I please see what your API Explorer really sends?

It shows you, except for the binary image contents! But if you need to see the POST body with the real binary image contents included, email us a small sample image; we can run a test in our lab and capture it for you. (We can't do this on our Production system.)

Shutterfly Open API | Image Upload

Description

Call Signature

Resource Path

Methods

Scheme

Host

Method: POST

Sample Input

Input Parameters

Sample Output

Output Feed

feed

upload-result entry

Error Codes

API Explorer

Frequently Asked Questions

General

User Authentication

API errors