API Documentation
API Key
In order to post data to Tagalus, you must enter an API key - this is not required to view data. To acquire your API key, first log in to Tagalus, then visit your user details page. If you enter an email address, an API key will be provided to you. Note that if you remove your email address, your API key will be invalidated. For security reasons, you should not share your API key, but in the event that it is leaked, you can always reset it.
API Calls
Data from the Tagalus API can be requested in two formats: JSON or XML. Errors are also returned in the requested format. If the parameter “callback=foo” is specified on a JSON request, the resulting JSON will be returned with the callback function specified.
Requests are currently of two types - ’show’ methods, which fetch data, and ‘create’ methods, which post data.
API ‘Show’ Methods
‘Show’ methods all fetch data from Tagalus - they don’t create or edit data, so all ’show’ methods don’t require authentication. If no items are found, null is returned. Show methods all require HTTP method “GET”
Methods
tag/[tag_name]/show.[format]
Example: http://api.tagal.us/tag/pdxtst/show.json
Returns: The tag and the corresponding definition with the highest authority
definition/[tag_name]/show.[format]
Example: http://api.tagal.us/definition/32/show.xml
Returns: All of the definitions corresponding to the tag specified in [tag_name]
comment/[tag_name]/show.[format]
Example: http://api.tagal.us/comment/32/show.xml
Returns: All of the comments corresponding to the tag [tag_name]
API ‘Create’ Methods
‘Create’ methods post data to Tagalus, and thus require authentication. Authentication is provided in the form of an API Key, a unique user key which can be found on the User Details page if you enter an e-mail address. Keys should be kept secret, but in the event that they become insecure, a new key can be generated on the User Details page. Keep in mind that this will invalidate the previous key. Create methods all recommend HTTP method “POST,” unless using JSON callbacks
Methods
tag/create.[format]
Example: http://api.tagal.us/tag/create.json
Required parameters: api_key = the user’s API key, the_tag = the name of the tag (max 100 chars), the_definition = a definition for the tag (max 280 chars)
Returns: If successful, the created tag
Note: if the tag already exists, an error will be thrown
definition/create.[format]
Example: http://api.tagal.us/definition/create.xml
Required parameters: api_key = the user’s API key, tag_id = the ID of the tag that the definition should be associated with (or the_tag if you prefer to refer to the tag by name instead of id), the_definition = a definition for the tag (max 280 chars)
Returns: If successful, the created definition
comment/create.[format]
Example: http://api.tagal.us/comment/create.json
Required parameters: api_key = the user’s API key, tag_id = the ID of the tag that the definition should be associated with (or the_tag if you prefer to refer to the tag by name instead of id), the_comment = a comment for the tag (max 280 chars)
Returns: If successful, the created comment
Errors
Errors are returned with an error message, and if available, an array containing specific array messages.
API Versions
The Tagalus API is released in versions, represented by a four digit number. The current release is 0001. In order to allow apps to continue functioning even when the API is updated, previous versions of the API will be available for a reasonable amount of time before they are deprecated. A specific API version can be requested with the parameter ‘api_version’, in either GET or POST requests. Please note that this is an optional parameter - if omitted, the latest version of the API will be used.
Example code
The following code sample (in PHP) would post a new tag, add a comment to the tag, and then retrieve the tag again, displaying the data for the user to see. The output is ugly, but it provides examples of quite a bit of the API functionality.
<?php
$api_key = "TEST_KEY";
$tagalus_api_url = "http://api.tagal.us/";
$test_suffix = 1;
$my_tag = urlencode("my_new_tag".$test_suffix);
$my_definition = urlencode("This is the definition for my tag".$test_suffix);
$my_comment = urlencode("This is my comment on my new tag".$test_suffix);
$url = $tagalus_api_url.'tag/create.json';
$curl_handle = curl_init();
curl_setopt($curl_handle, CURLOPT_URL, "$url");
curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 2);
curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl_handle, CURLOPT_POST, 1);
curl_setopt($curl_handle, CURLOPT_POSTFIELDS, "api_version=0001&api_key=".$api_key."&the_tag=".$my_tag."&the_definition=".$my_definition);
$buffer = curl_exec($curl_handle);
curl_close($curl_handle);
header("Content-type: text/plain");
echo $buffer."\n\n";
$data = json_decode($buffer);
if (isset($data->error)) {
echo "There was an error at step 1: ". print_r($data->errors);
exit;
}
$tag_id = $data->id;
echo "\n\nTag id: ".$tag_id. "\n";
$url = $tagalus_api_url.'comment/create.json';
$curl_handle = curl_init();
curl_setopt($curl_handle, CURLOPT_URL, "$url");
curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 2);
curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl_handle, CURLOPT_POST, 1);
curl_setopt($curl_handle, CURLOPT_POSTFIELDS, "api_version=0001&api_key=".$api_key."&tag_id=".$tag_id."&the_comment=".$my_comment);
$buffer = curl_exec($curl_handle);
curl_close($curl_handle);
echo $buffer."\n\n";
$data2 = json_decode($buffer);
if (isset($data2->error)) {
echo "There was an error at step 2: ". print_r($data2->errors);
exit;
}
$url = $tagalus_api_url.'tag/'.$my_tag.'/show.json';
$curl_handle = curl_init();
curl_setopt($curl_handle, CURLOPT_URL, "$url");
curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 2);
curl_setopt($curl_handle, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, 1);
$buffer = curl_exec($curl_handle);
curl_close($curl_handle);
$data3 = json_decode($buffer);
echo $buffer."\n\n";
if (isset($data3->error)) {
echo "There was an error at step 3: ". print_r($data3->errors);
exit;
}
echo "Tag: \n\n";
print_r($data3->the_tag);
echo "\n";
echo "Definition: \n\n";
echo print_r($data3->definition);
echo "\n";
echo "end";
?>
JavaScript Interface
In order to provide the easiest possible access to the API, Tagalus provides a JavaScript library that automates some of the behavior necessary to communicate with the Tagalus API via JSON requests. This same file also provides all of the functionality to add the Tagalus Widget to your page. Note that to use this file, you must also include jQuery somewhere in your page (you can always include the version that Google serves: http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js)
Looking at the source will give you the most insight in how to use the JS interface (the file is non-minified and has examples in the comments), but here are a couple of the most useful functions:
TagalusAPI.show_tag(tag,callback)
This function will provide data about a given tag. Data is returned via the callback function - eg TagalusAPI.show_tag(”tag”,function(data) { alert(data.definition.the_definition) });
TagalusAPI.create_definition(tag,definition,callback)
This function creates a definition for a tag. If the tag does not exist yet, it will be created. TagalusAPI.create_definition(”tag”,”my definition for the tag”, function(data) { }); Note that to use this function, you must provide an API key (TagalusAPI.api_key = ‘MYAPIKEY’)
TagalusAPI.api_call(uri,params,callback)
Calls the Tagalus API and executes callback when data is returned. Example: TagalusAPI.api_call(’tag/pdxtst/show.json’, {}, function(data) { alert(data.created_at) }