Feeds and Entries in GET requests

An Atom feed represents some specific resource - that is, it provides the data elements of the resource. An Atom entry does the exact same thing. The key difference between a feed and an entry is that a feed may additionally serve as a container for entries. The entries would/should be "children" (child resources) of the feed, and would usually be resources of a different type. For example, a user feed might have address book entries, or an album feed might have image entries. Some feeds are fictional, such as the "Query Results" feed which is merely a container for its entries: the results of the query.

An HTTP GET does a read 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>25</opensearch:totalResults>
<opensearch:startIndex>1</opensearch:startIndex>
<catinfo:categoryInfo term="addressbookentry" count="25"/>
<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 25 entries (25 total results), which will be listed starting with index 1 (1-based). The catinfo element says there will be 25 entries of category "addressbookentry" - although the entries are not all shown above. 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.

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 gave no "category-term=" parameter to request child resources (assuming an address book resource can have child resources, which might not be the case). Category-term is described below. For now, let's note that the example may just as well have come back as a standalone Atom entry; 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 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:

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.