API

Viewbook exposes an API for 3rd party tools to enhance Viewbook using the Flickr REST style API for it's request and response formats.

If you like to use the Viewbook API you need to apply for an api_key. Please send an email to info@viewbook.com , and we'll give you further instructions.

API implementation

Viewbook uses Flickr's REST implementation. Requests and responses are the same (with a few minor differences, see below), so you can follow the documentation at Flickr to implement the Viewbook API.

The REST endpoint URL for Viewbook is:
http://api.viewbook.com/services/rest/

To request the flickr.people.getUploadStatus method, invoke like this:


http://api.viewbook.com/services/rest/?method=flickr.people.getUploadStatus

See the documentation below for implemented API methods.

Differences to the Flickr API

The main differences are:
- Viewbook needs a photoset_id(required) for uploading.
- Viewbook does not offer functionality to replace images.

Authentication

Users should be authenticated using the Authentication API. The first step for desktop and other non-browser-based applications is to call the API method flickr.auth.getFrob, which requires signing. The response to the method call contains a 'frob' which should then be used to build a url to direct the user to the following url (opening in the system's default browser). Use this URL for authentication:

http://api.viewbook.com/services/auth/?api_key=[api_key]&perms=[perms]&frob=
					[frob]&api_sig=[api_sig]

Documentation: authentication API

Photo Upload API

This is the specification for building photo uploader applications. It works outside the normal API framework because it involves sending binary files over the wire. Uploading apps can call the flickr.people.getUploadStatus method compared in the regular API to obtain limits for the user. Photos should be POSTed to the following URL:

http://api.viewbook.com/services/upload/

photoset_id: Viewbook needs an extra argument called 'photoset_id (required)' containing the id of a photoset.
tags, is_public, is_friend, is_family, safety_level, content_type, hidden: Viewbook does not (yet) do anything with those properties.
redirection: Viewbook does not redirect after uploading a set of photos.
/services/replace: Viewbook does not support the replace method.

Documentation: upload API

Upload Status

Returns information for the calling user related to photo uploads. Use this method to check if the user can upload (did not reach limit, no locked account, etc)
XML response:

<rsp stat="ok"> 
  <user id="45678" locked="true/false" preferred_storage_location="US/EU"> 
  <username>username<username>
  <images created="3000" remaining="2000">

<rsp> 

Documentation: people.getUploadStatus

Photosets

flickr.photosets.getList
Returns the photosets (Albums in Viewbook) belonging to the specified user.
XML response:

<photosets cancreate="1" page="1" perpage="500" pages="1" total="2">

	<photoset id="5" primary="2483" secret="abcdef" updated_at="1302698241"
		server="8" photos="4" farm="1" status="ready|progress" is_private="true|false">
		<title>Test</title>
		<description>foo</description>
	</photoset>
	<photoset id="4" primary="1234" secret="832659"
		server="3" photos="12" farm="1" status="ready|progress" is_private="true|false">

		<title>My Set</title>
		<description>bar</description>
	</photoset>
</photosets>

To create a link to an album:

http://[username].viewbook.com/permalink/[id]/[secret]

Documentation: photosets.getList

flickr.photosets.create
Create a new photoset (Album in Viewbook) for the calling user.
private: true/false.
primary_photo_id: is not required with Viewbook.
XML response:

<rsp stat="ok">
  <photoset url="http://username.viewbook.com/name" id="27783"/>
</rsp>

Documentation: photosets.create


flickr.photosets.getPhotos
Get the list of photos in a set.
Supported options in the 'extras' argument: date_upload,last_update,url_sq,url_t,url_s,url_m,url_b,url_o,sq_height,t_height,s_height,m_height,b_height,o_height,sq_width,t_width,s_width,m_width,b_width,o_width (also see Flickr documentation)
Image description added in viewbook namespace

XML response:

<photoset id="4" primary="2483" page="1" perpage="500" pages="1" total="2" status="ready|processing" updated_at="1302698241">

	<photo id="2484" secret="123456" server="1" farm="1" title="my photo title" isprimary="0" status="ready|processing">
            <viewbook:description>my description</viewbook:description>
        </photo>
        <photo id="2484" secret="123456" server="1" farm="1" title="my photo title" isprimary="0">
            <viewbook:description>my description</viewbook:description>        
       </photo>

</photoset>

Documentation: photosets.getPhotos
Photo Source URLs: You can construct the source URL to a photo once you know its ID, server ID, farm ID and secret, as returned by many API methods above. Follow the documentation here .

Photo URL's

You can construct the source URL to a photo once you know its ID, server ID, farm ID and secret, as returned by many API methods.

The URL takes the following format:

http://farm{farm-id}.static.viewbook.com/{server-id}/{id}_{secret}_[size].jpg

The following image sizes are available:

sq => mini (40x40)
t => thumb (70x70)
p => preview (160x160)
s => small (320x)
m => medium (640x)
mm => medium_mobile (480x480)
b => large (1024x1024)
bm => large_mobile (1024x1024)
h => hd (1920x1080)
o => original