Shutterfly Open API  |  Atom Feeds, Entries, Categories, Pagination


Feeds and Entries in GET requests

In the Shutterfly Open API, an Atom <feed> represents some data resource - that is, it provides the data elements of the resource. An Atom <entry> does the same thing. Usually, it is an enduring resource such as a Shutterfly user, a user album, a user image, etc.

The key difference between a feed and an entry is that a feed can serve as a container for zero or more entries. The entries, when present, would usually be different kinds of resources that are logical "children" of the feed resource. For example, a user feed might have folder, album and address book entries for the given user; an album feed would usually have image entries for that album.

Some feeds returned by the Shutterfly Open API are ad hoc (or temporary) in nature. For example, you will sometimes see a "Query Results" feed which is intended not as an enduring resource, but as a mere container for its entries: the results of your query.

An HTTP GET does a read operation or query operation in Shutterfly's API, as per the REST model. The exact data that is returned depends on the request. Here is an example:

GET /userid/9AbNHLRq4ZE/addressbook

It is a query operation. It asks for the address book resources owned by user 9AbNHLRq4ZE. The result is an Atom feed with only a few elements at the feed level - mostly a description of the results: total results returned, start index, etc., as follows (for clarity, not all elements are shown):

<?xml version="1.0" encoding="UTF-8"?>
<feed>
   <opensearch:totalResults>15</opensearch:totalResults>
   <opensearch:startIndex>1</opensearch:startIndex>
   <catinfo:categoryInfo term="addressbookentry" count="15"/>
   <entry>
      <category term="addressbookentry" scheme="http://site.openfly.shutterfly.com/v1.0"/>
      <id>http://ws.shutterfly.com/userid/9AbNHLRq4ZE/addressbookid/48d28f5be4699ae9</id>
      <addressbookentry:nickName>Self</addressbookentry:nickName>
      <addressbookentry:firstName>Kris</addressbookentry:firstName>
      <addressbookentry:lastName>Kringle</addressbookentry:lastName>
      ...
   <entry>
   ...
</feed>

The result says that it contains 15 entries (15 total results), which will be listed starting with index 1 (1-based). The <catinfo> element says there will be 15 entries of category "addressbookentry" - although not all entries are shown above.

In the above example, it happens that the "addressbookentry" number equals the "totalResults" number - which is explained by the fact that the original query was for address book resources only. If the query had looked like this:

GET /userid/9AbNHLRq4ZE?category-term=addressbook,folder,album

then the results would have included more than addressbook entries. If there were 15 addressbook entries, 2 folder entries and 3 album entries, each would have had its own <catinfo> element, and the <totalresults> element would have said 20.

Here is another example:

GET /userid/9AbNHLRq4ZE/addressbookid/48d28f5be4699ae9

It is a read operation. It asks for one, specific address book resource. The result is an Atom feed whose elements describe that address book resource (for clarity, not all elements are shown):

<?xml version="1.0" encoding="UTF-8"?>
<feed>
   <category term="addressbookentry" scheme="http://site.openfly.shutterfly.com/v1.0"/>
   <id>http://ws.shutterfly.com/userid/9EcsnDRuyc/addressbookid/48d28f5be4699ae9</id>
   <addressbookentry:nickName>Self</addressbookentry:nickName>
   <addressbookentry:firstName>Kris</addressbookentry:firstName>
   <addressbookentry:lastName>Kringle</addressbookentry:lastName>
   ...
</feed>

Note that all data is at the feed level and there are no entries. The reason is that the query URL had no path element or "category-term=" parameter that would have requested child resources (assuming an address book resource can have child resources, which might not be the case).

Category-term is explained in further detail below. For now, let's note that the example above may just as well have come back as a standalone Atom entry. On single-resource queries, you can request >entry< format by including a "format=entry" parameter on the URL, like this:

GET /userid/9AbNHLRq4ZE/addressbookid/48d28f5be4699ae9?format=entry

<?xml version="1.0" encoding="UTF-8"?>
<entry>
   <category term="addressbookentry" scheme="http://site.openfly.shutterfly.com/v1.0"/>
   <id>http://ws.shutterfly.com/userid/9EcsnDRuyc/addressbookid/48d28f5be4699ae9</id>
   <addressbookentry:nickName>Self</addressbookentry:nickName>
   <addressbookentry:firstName>Kris</addressbookentry:firstName>
   <addressbookentry:lastName>Kringle</addressbookentry:lastName>
   ...
</entry>

Category Term

The "category-term=" parameter gives the ability to call for child resources along with the main resource - say, a user plus the user's folders, which is the following example:

GET /userid/9AbNHLRq4ZE?category-term=folder

This will return a feed that consists of user data and some folder entries:

<?xml version="1.0" encoding="UTF-8"?>
<feed>
   <category term="user" scheme="http://openfly.shutterfly.com/v1.0"/>
   <user:email>santa@northpole.org</user:email>
   <user:firstName>Kris</user:firstName>
   <user:lastName>Kringle</user:lastName>
   ...
   <catinfo:categoryInfo term="folder" count="2"/>
   <entry>
      <title>My New Folder</title>
      <category term="folder" scheme="http://media.openfly.shutterfly.com/v1.0"/>
      <id>
         http://ws.shutterfly.com/userid/9AbNHLRq4ZE/folderid/9695c5a007cd47446a1c380087faa9ab
      </id>
      ...
   </entry>
   ...
</feed>

So the returned data tells you about the user at the feed level and that the user has two folders, the data of which are returned as entries.

Notes

  • Multiple category-terms may be requested simultaneously - just divide them with a comma, for example category-term=addressbook,folder
  • Not all child resources are supported by category-term at the current time. We are moving toward full support, but please refer to the API documentation for the supported category-term values for that particular API.

Limitations

Some API's return certain child resources even when you don't request it with a category-term. This is in error and will be fixed, but let's walk through the current state of the world.

  • User API. At the moment, this API returns album entries. This behavior should NOT be relied upon as it will be removed shortly. If you want both user and album data in the same feed, please use "category-term=album". That is, request something like /user/XYZ?category-term=album. If you do NOT want the album data in the user feed, you can say "category-term=none" for this API, which will return just the user data (this will be the default behavior in the future).
  • Album API. At the moment, this API returns image data by default. Again, this behavior should NOT be relied upon as it will be removed shortly. Please use "category-term=image", such as /user/XYZ/album/123?category-term=image. Unfortunately there is no "none" category-term work-around for this API at the current time as the Image API is being developed. Therefore, we recommend that you always use "category-term=image" in the URL until we rectify the issue.

Pagination

Shutterfly supports server-side pagination of results. Here are the parameters:

max-results
The maximum number of results to return on this query.
start-index
The starting index (1-based) to return. That is, if there are 25 results but you want the second page of 10, you would set max-results to 10 and start-index to 11.

Note that the result will contain additional information about the query:


<?xml version="1.0" encoding="UTF-8"?>
<feed>
   <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
   <opensearch:totalResults>25</opensearch:totalResults>
   <opensearch:startIndex>11</opensearch:startIndex>
   <catinfo:categoryInfo term="addressbookentry" count="10"/>
   <entry>
...
</feed>
        

The opensearch terms refer to the query requested - itemsPerPage should match max-results, startIndex should match start-index, and totalResults will tell you the total data available. The catinfo term refers to the data actually returned on this request - that there are 10 entries of category "addressbookentry" coming now. Note that if you overshoot (if you request start-index of 100 on this query, for example), the catinfo element will not show up at all - it is only present to tell you about what data is coming.

Limitations

  • Pagination is only supported for "query" requests. That is, if you ask for one particular object - say /userid/XYZ, there is no pagination support (after all, you're only asking about one object). If you ask for a number of objects - say, /userid/XYZ/addressbook or /userid/XYZ?category-term=album - then pagination is supported.
previous
User
Authentication
next
Create User
© 1999-2014 Shutterfly, Inc. All rights reserved.