Gallery3:API:Flickr

If looking for REST docs, (See Gallery3:API:REST).

We're building a new API based on the [Flickr API]. To figure out scope, we'll be picking a few popular Flickr API clients, analyzing what API calls and transports they use, and building endpoints as a module in Gallery 3 so that these clients can work with Gallery 3 just by changing the API endpoints that they use.

Popular Photo Management Tools and How They Talk To Flickr

Picasa - plugin: http://picasa2flickr.sourceforge.net/
iPhoto - plugin: http://connectedflow.com/flickrexport/ the baked in support works differently: http://speirs.org/2009/01/30/on-the-flickr-support-in-iphoto-09/
Lightroom - plugin: http://regex.info/blog/lightroom-goodies/flickr
F-Spot - built in using: http://www.codeplex.com/FlickrNet
client API list is on: http://www.flickr.com/services/api/

Client API Usage

iPhoto Native Flickr Support

got a capture of creating a private set with 2 items and then deleting it

$ sudo tcpdump -s 0 -A -i en1 port 80 > dump.txt
$ egrep "GET" dump.txt | cut -d '=' -f 5 | cut -d '&' -f 1 | cut -d ' ' -f 1 | grep -v 0 | sort | uniq

flickr.auth.checkToken
flickr.people.getInfo
flickr.photos.delete
flickr.photos.geo.removeLocation
flickr.photos.getInfo
flickr.photos.setTags
flickr.photosets.addPhoto
flickr.photosets.delete
flickr.photosets.editPhotos
flickr.photosets.getList

POST stuff was harder to nab but ends up being calls to: /services/upload/ following the upload API and posts to /services/rest/ for:

flickr.photos.setMeta
flickr.photos.getPerms
flickr.photosets.create

iPhoto Flickr Export Plugin

got a capture of creating a private set with 1 new item uploading

flickr.auth.checkToken
flickr.auth.getToken
flickr.groups.pools.getGroups
flickr.photosets.getList
flickr.photosets.create
flickr.prefs.getContentType
flickr.prefs.getHidden
flickr.prefs.getSafetyLevel
flickr.test.login
flickr.urls.getUserPhotos
flickr.people.getUploadStatus

POST to /services/upload and post to /services/rest/ for:

flickr.photos.upload.checkTickets
flickr.photos.setDates
flickr.photos.setTags
flickr.photos.setMeta

Lightfroom Flickr Plugin

got a capture of creating a new set with one photo uploading

$ sudo tcpdump -s 0 -A -i en1 port 80 > dump.txt

GET:

flickr.photos.geo.setPerms
flickr.photos.setMeta
flickr.photosets.create
flickr.photos.getInfo

POST: just to /services/upload/

Notable Details

Some other people are mirroring Flickr's API: Other people mirroring flickr's API: http://www.23hq.com/doc/api/
Flickr uses "keys" that are application specific, and has "shared secrets" that are associated with keys and required for some API calls
Flickr client config is the api key and shared secret. API entry points are coded into libraries somewhere but can be changed in some implementations ($f->REST = "http://foo/entry" in one of the php clients)
Method calls are named flickr.*. We should call our subset gallery3.* but should also respond to flickr.* calls
We should treat photosets as albums, Flickr doesn't support nesting so we would use path for title and use Gallery's auto url stuff. ex: "Spring Break/2009/Awesome Stuff" would be a collection title, that would be come spring_break/2009/awesome_stuff on G3
Photos uploaded aren't put into a set by default. Do we have a config for default upload location or add parameter for "set"? (see http://www.flickr.com/services/api/upload.api.html )
Flickr auth uses keys/etc for login, so our login process will have to work differently. Can we squish user/pass into this or use our own auth api? (see http://www.flickr.com/services/api/auth.spec.html )
Plenty of things work with unauthenticated calls, do we want to let this happen?
The API has tight integration with tags, do we make this API depend on tags?
entry points like:
- services/auth/ -> special case
- services/upload/ -> special case, http post with binary data
- services/replace/ -> special case, http post with binary data
- services/rest/
- services/xmlrpc -> can do this later
- services/soap -> can do this later
response format can be specified as a paramater
- rest
- xmlrpc
- soap
- json
- PHP serialize/unserialize

Usage Scenarios

Step 1: Logging in

gallery3/services/auth

(inspiration: http://www.flickr.com/services/api/auth.spec.html)

post of user/password to url
gets back status code, session token, and request token

Gallery3 authenticates the user, assigns a token for this session, and gives a request token (like existing security form tokens) that changes every request

Step 2: Uploading a photo

gallery3/services/upload

(inspiration: http://www.flickr.com/services/api/upload.api.html )

post of photo and information, including album path
gets back status code, image ID, image URL, and a new request token.

Personal tools