Basic Flow

The following list of steps represents the typical sequence of events that will ensue when a new TagCow.com user uses your application. This is provided for demonstration purposes only. Application developers are encouraged to be creative and make a process that works best for their users and make the integration as seamless as possible.

This application will upload all of the images in a directory on the users computer and place the tags provided by TagCow.com into the images IPTC header. This will allow the user to search for the images using an application like Picasa or Windows Search.

1. User creates and activates a TagCow.com account (there are no API methods for this)
2. User starts your application
3. User is prompted for their TagCow.com user credentials
4. Application calls API to generate an application session.
   1. These session credentials will be used in subsequent API requests.
5. Application calls API to submit an image for tagging
   1. This API call will upload the image to TagCow.com and start the tagging process
   2. The image will now appear in the users images list on TagCow.com
6. TagCow.com performs requested tagging
7. Application polls taggings for new entries
8. When new taggings are returned, the application places the tags into the corresponding image files IPCT keywords header field
9. User searches for a keyword (e.g. beach, family, Disneyland) using Picasa
10. Search returns all images that have the requested tag

RESTful API

The TagCow.com API was designed using a RESTful style. To learn more about RESTful style APIs refer to the this article.

Authentication

In order to use any TagCow API, an application must have a set of keys. There are two keys: a Public Key and a Private Key (these keys should be kept secure).

Public Key

The Public Key is sent with every request. It identifies the requester.

Private Key

The Private Key is used to generate a request token for each request. It is never sent in the clear!

Application Session Creation

In order for an application to interact with the TagCow.com API, a session must be established using the Public Key, Private Key, User Login, and User Password. A session is identified by a Session ID. Once the session is created, all interactions with the API will be made with this session ID.

Signature And Date

A signature is required to be sent with all API calls. It is generated for every request using the Private Key and Date. The Date is also sent with the request and cannot be more than 10 minutes in the past or future.

Generate the signature in the following way:

• Date=RFC2822 formatted date/time (example: “Fri, 06 Jun 2008 22:29:20 -0600”, see http://www.rfc.net/rfc2822.html#p14 for more information)
• Pre-Hash Value=Private Key + Date (no separation)
• Signature=SHA1 Hash of Pre-Hash Value

Request Format

POST Requests

http://api.tagcow.com/<class>/<id>(if applicable).xml

Post Fields:
	date=Exact date used to create signature
	public_key=Public Key
	signature=Authentication Signature
	date=Date
	session_id=Session ID
	parameter1=value
	parameter2=value

GET Requests

http://api.tagcow.com/<class>/<id>(if applicable).xml?date=<date>&public_key=<API Key ID>&signature=<Authentication Signature>&session_id=<Session ID>¶meter1=<value>

Note that the date needs to encoded in the URL for GET requests, but should NOT be encoded to generate the signature.

Example:

The following query is creating one image entry on the TagCow.com system:

http://api.tagcow.com/images

POST Fields
	public_key=903d20c8efd0f1f52b7764713fcc0b926c92947f
	signature=591cf14e0921efd4478fd202adac3577e35e3ec8
	Date=Mon, 04 Aug 2007 16:12:24 -0600
	session_id=be66dea34e5d9ba06f7e4552a8be7d112b6c0cfa
	File1=<File>

Document Convention:

The following convention will be used to describe the API operations:

<apiresponse>
    ...
</apiresonse>

Operations

This section describes the classes and operations that are available on them. Use the following convention:

<apiresponse>
	<response>Success | Failure</response>
	<message></message>
	<session_id>[Session ID]</session_id>
</apiresonse>

http://api.tagcow.com/app_sessions/be66dea34e5d9ba06f7e4552a8be7d112b6c0cfa?session_id=be66dea34e5d9ba06f7e4552a8be7d112b6c0cfa

<apiresponse>
	<response>Success | Failure</response>
	<message></message>
	<session_id>[Session ID]</session_id>
</apiresonse>

<apiresponse>
	<response>Success | Failure</response>
	<message></message>
	<images>
		<image>
			<id>[unique image id]</id>
		</image>
		...
	</images>
</apiresonse>

<apiresponse>
	<response>Success | Failure</response>
	<message></message>
	<total_entries></total_entries>
	<total_pages></total_pages>
	<count></count>
	<images>
		<image>
			<id>[unique image id]</id>
			<source_id>[provided source id]</source_id>
			<status>
				<id></id>
				<description></description>
			</status>
			<taggings>
				<tagging>
					<id>[unique tagging id]</id>
					<tag>[tag]</tag>
					<machine_tag>true | false</machine_tag>
					<workflow>descriptive | people | content_moderation</workflow>
				</tagging>
				...
			</taggings>
		</image>
		...
	</images>
</apiresonse>

http://api.tagcow.com/images/312332?session_id=be66dea34e5d9ba06f7e4552a8be7d112b6c0cfa...

<apiresponse>
	<response>Success | Failure</response>
	<message></message>
	<image>
		<id>[unique image id]</id>
		<source_id>[provided source id]</source_id>
		<status>
			<id></id>
			<description></description>
		</status>
		<taggings>
			<tagging>
				<id>[unique tagging id]</id>
				<tag>[tag]</tag>
				<machine_tag>true | false</machine_tag>
				<workflow>descriptive | people | content_moderation</workflow>
			</tagging>
			...
		</taggings>
	</image>
</apiresonse>

http://api.tagcow.com/images/38849?session_id=be66dea34e5d9ba06f7e4552a8be7d112b6c0cfa...

<apiresponse>
	<response>Success | Failure</response>
	<message></message>
	<images>
		<image>
			<id>[unique image id]</id>
		</image>
	</images>
</apiresonse>

<apiresponse>
	<response>Success | Failure</response>
	<message></message>
	<total_entries></total_entries>
	<total_pages></total_pages>
	<count></count>
	<taggings>
		<tagging>
			<id>[unique tagging id]</id>
			<image_id>[unique image id]</image_id>
			<source_id>[provided source_id]</source_id>
			<tag>[tag]</tag>
			<machine_tag>true | false</machine_tag>
			<workflow>descriptive | people | content_moderation</workflow>
		</tagging>
		...
	</taggings>
</apiresonse>

Image Tagging Result Callback

An alternative to using the taggings get method to poll for new tagging results is to use the Image Tagging Result Callback feature. Using this feature, will cause TagCow to proactively post the results of a tagging back to a provided URL once an image tagging is completed. This feature enables high-volume customers to more easily scale their solution. The provided URL needs to point to a high-availability web application. The URL will only be called once and does not check the result of the call. If web application is not able to process the post, then the application owner will be responsible for using the taggings GET or images GET/[image_id] to request the tagging results. The callback URL will be called with a GET HTTP method and the following query string format:

Given a callback URL of http://www.samplecallbackurl.com the callback post would be in the following format:

http://www.samplecallbackurl.com?image_id=[unique image id]&tag0=[tag]&tag1=[tag]&tagN=[tag]

Given a callback URL of http://www.samplecallbackurl.com?custom_variable=1332 the callback post would be in the following format:

http://www.samplecallbackurl.com?custom_variable=1332&image_id=[unique image id]&tag0=[tag]&tag1=[tag]&tagN=[tag]