About the API

Fotopic.Net offer a free method of building access to photo gallery administration into your own software, using a combination of HTTP POST and XML technologies.

Put simply, the 'Toolkit' system allows remote usage of Fotopic systems within scripts, basically giving an alternative to the "my.fotopic" system which can be built into other applications and user agents. It is called via an HTTP or HTTPS interface at "toolkit.fotopic.net". Use of the HTTPS interface is encouraged in preference to the HTTP method.

Using this method, users of your application can:

• Retrieve photo, collection and gallery data using the Fotopic XML schema.
• Publish photos through a method other than those supported by my.fotopic.net.
• Remotely administer their photo gallery without using the my.fotopic.net interface.

About XML

XML is a document description language, much like the Hypertext Markup Language (HTML) that is used to construct web pages. XML, however, is much more versatile than HTML and as such has profound implications on how we view what the web is and what it can do.

HTML has a set of predefined tags that describe components of a document and how a browser should present that information. XML shares many of the same characteristics of HTML and looks very similar, however, it is far more flexible. Using either Document Type Definitions (DTDs) or an XML-Schema, it is possible to define new tags that are useful for a wide variety of applications. These applications can range from an information presentation format like HTML, to an electronic business application. XML is a rapidly growing technology with many applications being created every day.

Fotopic has developed a set of DTDs that define tags and a data format that can be used to purchase and manage a number of products and services. For more information on XML the reader is referred to the website http://xml.com. Additional useful information concerning specifications and the standardization process is available at the site http://www.w3c.org/xml, which is the official site for XML development.

Note about State

It should be noted that the tookit system is stateless - no call bears any context, and using this it is possible to create flexible systems which don't require things like cookie handling and suchlike. The drawback is that username/password information has to be sent with each call, but this isn't so bad.

Making Calls

Each call to the toolkit system should be made with an HTTP POST request, formed of the following basic variables with each call:

Field	Description
u	Username
p	MD5sum of the password
action	Function to be carried out

Dependent on "action", there may be more calls required. For instance, the 'add' function takes several parameters to indicate whether the user wishes to add a gallery, a collection, etc.

Note that the password must NOT BE PASSED IN PLAIN TEXT. An md5 sum of the password must be passed which is then compared server-side, and an error generated if this is the incorrect password. Each password attempt is logged. Bear in mind that if the HTTP interface is used, the md5 sum may be intercepted and misused by a third party. For this reason, the HTTPS interface should be used wherever possible.

It's not possible to modify any objects which are not associated with the logged in user - ie. no global administration is possible through the toolkit method.

When a function is called, it returns results in the XML format described in http://www.fotopic.net/xml/fotopic.xsd (XML Schema format). This may be a partial or full description of the object created.

The <result>..</result> container will either contain "OK" or "ERROR", depending on what happened. Extra information about the operation may be passed in the <comment>..</comment> container.

These can then be used to cascade calls such as building a gallery, then the collections, and the photos within those collections.

Functions

This function list details functions and parameters in the following format:

object.action

Supported functions are:

Function:	gallery.list
Description:	List a user's galleries
Variables:	<none>
Returns:	A list of gallery objects
Function:	collection.list
Description:	List a gallery's collections
Variables:	galid	Gallery ID number
Returns:	A list of collection objects
Function:	collection.get
Description:	Get a collection
Variables:	colid	Collection ID number
Returns:	Collection object
Function:	collection.add
Description:	Add a blank collection to a gallery
Variables:	galid	Gallery ID number
	coltitle	Collection Title
	coldatestart	Collection Date Start in "YYYY-MM-DD" format
	coldateend	Collection Date End in "YYYY-MM-DD" format (optional)
	colcopyright	Collection Copyright (optional)
	colrating	Collection Adult Rating (0=unrated, 1=adultflag) (optional, default 0)
Returns:	The newly created collection object
Function:	collection.checkin
Description:	Add a collection to a gallery, and check in all photos in 'incoming' directory
Variables:	galid	Gallery ID number
	coltitle	Collection Title
	coldatestart	Collection Date Start in "YYYY-MM-DD" format
	coldateend	Collection Date End in "YYYY-MM-DD" format (optional)
	colcopyright	Collection Copyright (optional)
	colrating	Collection Adult Rating (0=unrated, 1=adultflag) (optional, default 0)
Returns:	The newly created collection object. This is used if you do not want to pass any special parameters to the 'photo.add' function, and is given as a shortcut to check in all photos and a collection at the same time. Images must be in jpeg format, and are given the date of the prevailing collection.
Function:	photo.list
Description:	List a collection's photos
Variables:	colid	Collection ID number
Returns:	A list of photo objects
Function:	photo.add
Description:	Add a photo to a collection (needs multipart encoding with POST method)
Variables:	colid	Collection ID number
	phfile	Photo file (in multipart format - see below for example)
	phdesc	Photo description
	phdate	Photo date/time in "YYYY-MM-DD" or "YYYY-MM-DD HH:MM" format
	phpassword	Password to set
	phrotate	Image rotation factor (0=none,1=90,2=180,3=270)
Returns:	The newly created photo object
Function:	photo.get
Description:	Get a photo's data
Variables:	phid	Photo ID number
Returns:	Photo object
Function:	photo.getfile
Description:	Get a photo's image file
Variables:	phid	Photo ID number
Returns:	JPEG photo original, or XML error

Functions which are either planned, in development, or simply undocumented at this stage:

gallery.add
gallery.drop
gallery.get
gallery.set

collection.drop
collection.get
collection.set

photo.drop
photo.set
photo.get
photo.getfile

user.get
user.set

Publishing Photos

In order to publish a photo you need to send the file via a POST request. The file must have the form attribute name "phfile", and the filename must not already exist within the collection (you can check this with the "collection.list" method).

The following form code shows how to upload a photo:

Examples

This URL will retrieve a list of galleries for the username "bob@smelly.org":

http://toolkit.fotopic.net/?action=gallery.list&u;=bob@smelly.org&p;=0203ad986a53f2b1c473831b9d53

<?xml version="1.0" encoding="UTF-8"?>

<result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:noNamespaceSchemaLocation="http://fotopic.net/xml/fotopic.xsd">

	<resultcode>OK</resultcode>

	<gallery id="994" user="1534">
		<title>Bob's Photo Gallery</title>
		<hostname>bobsphotos.fotopic.net</hostname>
		<created>2002-02-25</created>
		<skin>20</skin>
	</gallery>

</result>

https://toolkit.fotopic.net/?action=collection.list&u;=bob@smelly.org&p;=0203ad986a53f2b1c4730831b9d53&galid;=1

Contacting Us

Queries about the toolkit and its functionality may be addressed to toolkit@fotopic.net.