Share it Live 1.0 : API Documentation

(document version 1.4 2009.06.30)

Introduction:

Share it Live exposes some of its functionality via an Application Programming Interface (API). This document aims to serve as a reference for developers building tools to talk to Share it Live.

Table of Contents:

About the API:

Share it Live provides a RESTful API for developers to work with. In addition, to explicitly stating the desired action as part of the URI of a HTTP request, the GET, POST, PUT and DELETE request methods are supported.

Where possible, this API tries to adhere to a Resource Oriented Architecture. The object being operated on will, in most cases, be specified as part of a request URI as opposed to a query string parameter.

Parameters are generally passed via query string in GET requests, as form fields in POST requests, or as query string-like name/value pairs in the body of PUT requests.

While the API is public, certain methods require permission or authentication to use. This may be achieved by authenticating with an OpenID, or by acquiring an API key for your application.

Getting an API Key

API Keys grant third party developers access to methods that manipulate data without the need to have an authenticated OpenID user. You may request an API key via our Get Satisfaction page.

API Error Messages

The API returns all error messages as an HTTP status code. Certain errors will direct you to the documentation and may include a more detailed description of the error at the top of the returned page.

API Result Formats

Data may be requested from the API in four supported formats by adding a dot extension to a request. The supported formats are RSS, ATOM, JSON and PLIST.

To get a list of posts in each of the supported formats you would structure your query like so:

http://api.shareitlive.com/1.0/posts.rss
http://api.shareitlive.com/1.0/posts.atom
http://api.shareitlive.com/1.0/posts.json
http://api.shareitlive.com/1.0/posts.plist

You must specify for any query that fetches content but not for queries that create, modify or delete content.

Authenticating Requests

Requests that manipulate data require authentication either via an OpenID or via formulating requests with an API key. The OpenID method authenticates an individual user's session an any requests that are made during that session. The API key method authenticates individual requests.

Login/Logout with OpenID

To login, make a GET request to the API's login controller passing an OpenID as the final section of the URI. For example, to login a user who has the OpenID of bobsmith.myopenid.com the following call is made:

http://api.shareitlive.com/1.0/login/bobsmith.myopenid.com

The OpenID response must include the user's full name, nickname and email address. A successful call starts a typical cookie-based session.

To logout, a similar API call is made:

http://api.shareitlivecom/1.0/logout

API Key Request Signing

An application may bypass OpenID authentication by signing all non-GET requests with an API key (see the section on acquiring an API for more information). Your API key includes a public id, and a secret key that is used to salt an md5 hash of your request. A request is signed in the following manner:

  1. In addition to the required request parameters, include your public id and the timestamp of your request in milliseconds. Your public id should be named "identity" and your request's timestamp should be named "timestamp"
  2. Alphabetize the order of the parameter names.
  3. Concatenate the values of your parameters and include your secret key as the final value.
  4. Create an md5 hash of the concatenated values.
  5. Add the md5 hash to your request parameters as a key/value pair named "hash". This is the signature of your request.
  6. Make the call to the API. DO NOT include your secret key.

The shareitlive api will look up the application's secret key based on the value passed for the public id. Next, it will check the timestamp of your request with the system time of the server. If the request was not made within the allowable threshold it will fail, (it is considered stale). If the request is timely, the api will attempt to recreate the hash with the passed parameters. If the hash passed in the request matches the hash created by the server, the request is treated as coming from a trusted source and is allowed to continue. Otherwise the request is unauthorized and fails.

Working with Posts

Retrieving a List

A list of posts is retrieved by making a GET request to the posts controller's index method, and specifying the result format. It is not necessary to explicitly state the index method in the GET request, the API will assume that a GET request should map to the index method when a post id is not included in the URI. The following examples demonstrate calls to the posts controller's index method:

http://api.shareitlive.com/1.0/posts.rss
http://api.shareitlive.com/1.0/posts.atom
http://api.shareitlive.com/1.0/posts.json
http://api.shareitlive.com/1.0/posts.plist

http://api.shareitlive.com/1.0/posts/index.rss
http://api.shareitlive.com/1.0/posts/index.atom
http://api.shareitlive.com/1.0/posts/index.json
http://api.shareitlive.com/1.0/posts/index.plist

Several parameters are supported in requests to the posts index controller.

count
Sets the number of records returned up to a maximum of 100. The default is 20. When used with the page parameter it is possible to paginate through multiple views of records.
page
Sets the page of results to return. When used with the count parameter it is possible to paginate through multiple views of records.
sdate
Limits the results to just posts that were made after the specified starting date. The format should by YYYY-MM-DD HH:MM:SS.
edate
Limits the results to just posts that were made before the specified ending date. The format should by YYYY-MM-DD HH:MM:SS.
city
Limits the results to just posts from the specified city.
state
Limits the results to just posts from the specified state.
zip
Limits the results to just posts from the specified postal code.
latitude
Must be used in conjunction with longitude. Limits the results to just posts from the specified lat/lon. If lat and lon are specified other address criteria are ignored.
longitude
Must be used in conjunction with latitude. Limits the results to just posts from the specified lat/lon. If lat and lon are specified other address criteria are ignored.
miles
Decimal value. Used in conjunction with latitude and longitude. Expands the results to include all posts within the the specified distance that match any other supplied parameters.
km
Decimal value. Used in conjunction with latitude and longitude. Expands the results to include all posts within the the specified distance that match any other supplied parameters.
search
Allows for rudimentary keyword searches in the description of posts. Only posts whose descriptions contain the specified keyword are returned.
tags
A comma delimited string of tags. Results are inclusivly limited to posts with one or more of the specified tags.

The result includes the total number of items matching the specified GET query. The total is defined as a category node in an ATOM or RSS formatted result, or as a more naturally occurring data point in a JSON or PLIST formatted result.

Retrieving a Single Post

An individual post is retrieved by making a GET request to the post controller's show method and including the ID of the post in the URI followed by the result format. It is not necessary to explicitly state the show method in the GET request, the API will assume that a GET request should map to the show method for the specified post ID. The following examples demonstrate calls to the posts controller's show method:

http://api.shareitlive.com/1.0/posts/10.rss
http://api.shareitlive.com/1.0/posts/10.atom
http://api.shareitlive.com/1.0/posts/10.json
http://api.shareitlive.com/1.0/posts/10.plist

http://api.shareitlive.com/1.0/posts/10/show.rss
http://api.shareitlive.com/1.0/posts/10/show.atom
http://api.shareitlive.com/1.0/posts/10/show.json
http://api.shareitlive.com/1.0/posts/10/show.plist

Creating a new Post

A new post is created by making a multipart form POST request to the post controller's create method that includes the required parameters to create a new entry. A result format should not be specified for this call. It is not necessary to explicitly state the create method in the POST request, the API will assume that a POST request should map to the create method. The following examples demonstrate calls to the post controller's create method:

http://api.shareitlive.com/1.0/posts
http://api.shareitlive.com/1.0/posts/create

The following parameters are available for a call to the create method:

udid
(required) The unique id of the poster within the the developer's application or framework.
image
(required) The photo being uploaded.
description
(optional) A description of what is happening in the photo.
latitude
(optional) The latitude where the event happened.
longitude
(optional) The longitude where the event happened.
address
(optional) The street address where the event happened.
city
(optional) The city where the event happened.
state
(optional) The state where the event happened.
zip
(optional) The postal code where the event happened.
email
(optional) The email address of the user submitting the post. This is optional in the API but recommended in practice.
tags
(optional) A comma delimited list of tags that should be applied to the new post.
referrer
(optional) If this optional boolean value is included the API will check the HTTP request headers for a referrer. If a referrer is present an HTTP redirect to the referrer will be made after a successful post.

Editing an existing Post

An existing post may be edited (or flagged) by making either a POST or a PUT request to the post controller's update method. If a PUT request is made, it is not necessary to specify the update method in the URI. If a POST request is made then the update method must be specified in the URI. The ID of the post to update should be included in the request URI. A result format should not be specified for this call. The following examples demonstrate calls to the posts controller's update method:

(PUT) http://api.shareitlive.com/1.0/posts/10
(POST) http://api.shareitlive.com/1.0/posts/10/update

The following parameters are available for a call to the update method:

flag
(optional) Flags the post as inappropriate. If flag is set then other parameters will be ignored.
description
(optional) A description of what is happening in the photo.
latitude
(optional) The latitude where the event happened.
longitude
(optional) The longitude where the event happened.
address
(optional) The street address where the event happened.
city
(optional) The city where the event happened.
state
(optional) The state where the event happened.
zip
(optional) The postal code where the event happened.
email
(optional) The email address of the user submitting the post. This is optional in the API but recommended in practice.
referrer
(optional) If this optional boolean value is included the API will check the HTTP request headers for a referrer. If a referrer is present an HTTP redirect to the referrer will be made after a successful post.

Deleting an existing Post

An existing post may be deleted by making either a POST or a DELETE request to the post controller's delete method. If a DELETE request is made, it is not necessary to specify the delete method in the URI. If a POST is made then the delete method must be specified in the URI. The ID of the post to delete should be included in the request URI. A result format should not be specified for this call. The following examples demonstrate calls to the posts controller's delete method:

(DELETE) http://api.shareitlive.com/1.0/posts/10
(POST) http://api.shareitlive.com/1.0/posts/10/delete

The following parameters are available for a call to the delete method:

referrer
(optional) If this optional boolean value is included the API will check the HTTP request headers for a referrer. If a referrer is present an HTTP redirect to the referrer will be made after a successful post.

Posts API Examples

How do I get a list of posts from the api to display in a custom widget?

Make a call to the api to retrieve a list of posts in the desired format, either rss, atom, json, or a plist. Limit the number of results returned, paginate through the result set, or limit the results to a search term by passing the appropriate parameters in the query string of the api call.

The following query will return the first page of posts with the hash tag "traffic" in Oklahoma City at ten posts per page in the RSS format:

http://api.shareitlive.com/1.0/posts.rss?count=10&page=1&city=Oklahoma+City&search=%23traffic

The following query will return the detail information about a specific post with an ID of 42:

http://api.shareitlive.com/1.0/posts/42.rss

How do I submit a news post to Share it Live via an html form?

Create the form that will handle the submission. Fields for a unique individual identifier, and the image are required. Fields for an email address, description, and location information are optional, but encouraged. Your form might look like the following:

<form name="myForm" method="post" enctype="multipart/form-data">
<input type="image" name="image" />
<input type="hidden" name="udid" value="1234" />
<input type="text" name="description" />
<input type="hidden" name="city" value="oklahoma city" />
<input type="submit" />
</form>

The udid field should be a unique identifier that is tied to a specific user. That user should always have the same udid.

Satisfying the API key requirements.

The sample form above is missing some key features, namely an action parameter, and the necessary API key information for a third-party developer including the developer's public id, a timestamp and an md5 hash of the form values. Naturally the timestamp and the md5 hash cannot be set until the moment the request is made.

You have a decision to make about how you post your form at this point. Option1: add the missing API key information via javascript before the form is submitted. Option 2: Post the form to your own handler page to add the missing information then post to the Share it Live API from there. You're choice will determine what needs to be set for the form's action parameter. Let's look at both options.

Option 1: Javascript

If you wish to provide the required fields via javascript when the form is posted you can set the form tag's action parameter to the Share it Live api. Add hidden form fields for the developer identity, timestamp, and authtoken. Finally add an onSubmit even handler for a javascript method. Besure to add a hidden field for referrer to redirect your user back to the referring page.

<form name="myForm" method="post" enctype="multipart/form-data" action="http://api.shareitlive.com/1.0/posts/create" onsubmit="return handleMyFormSubmit();">
<input type="hidden" name="identity" value="myPublicId" />
<input type="hidden" name="timestamp" value="" />
<input type="hidden" name="authtoken" value="" />
<input type="hidden" name="referrer" value="yes" />

<input type="image" name="image" />
<input type="hidden" name="udid" value="1234" />
<input type="text" name="description" />
<input type="hidden" name="city" value="oklahoma city" />
<input type="submit" />
</form>

Now write the javascript to fill out the missing information. (Note that you will need to acquire a third-party javascript library such as JQuery, or Dojo to calculate the md5 hash.)

    <script>
    function handleMyFormSubmit(){
        var mySecretKey = "asreLKJL22340ask2lazz09q4ri";  // In practice you should never expose your secret key this way.
        var d = new Date(); //Create a date object so we can get a timestamp.
        document.myForm.timestamp.value = d.valueOf();
    
        //Form fields in alphabetical order
        var reqStr = document.myForm.city.value;
        reqStr += document.myForm.description.value;
        reqStr += document.myForm.identity.value;
        reqStr += document.myForm.timestamp.value;
        reqStr += document.myForm.udid.value;
        reqStr += mySecretKey;
        var hash = md5(reqStr);
    
        document.myForm.authtoken.value = hash;

        return true;
    }
    </script>

Keep in mind that the only form field that is not to be included in the authtoken hash is the authtoken itself. If you give a name to your submit button, you will need to include its value in the hash.

Warning: Your secret key is exposed in the source of your javascript if you use this option. It is less secure than Option 2 and is therefore not recommended.

Option 2: Proxying the submission

You may proxy the post to the Share it Live api by submitting to your own form handler, and then making the post from your web page. Different server-side technologies will accomplish this is different ways. PHP is used for this example.

Set the form's action paramater to the url of your custom form handler.

<form name="myForm" method="post" enctype="multipart/form-data" action="/myFormHandler.php">
<input type="image" name="image" />
<input type="hidden" name="udid" value="1234" />
<input type="text" name="description" />
<input type="hidden" name="city" value="oklahoma city" />
<input type="submit" />
</form>

The myFormHandler.php script will receive the form post, compose the information with the required api information, and then make the call to the api. 

//myFormHandler.php

require_once "HTTP/Request.php";

#
#   You need to supply a udid for each post to identify the posting agent.
#
$udid = "UNIQUE_USER_IDENTIFICATION_STRING";
$secret = "YOUR_SECRET_API_KEY_USED_TO_SIGN_YOUR_REQUEST";
$identity = "YOUR_PUBLIC_IDENTIFIER_FOR_THE_API";


#
#   Check for an uploaded file.
#
if(empty($_FILES["image"])){
    redirectToReferer();
    die();
}


#
#   Prepare an http request to handel the upload and attach the uploaded file
#
$req = new HTTP_Request($server);
$req->setMethod(HTTP_REQUEST_METHOD_POST);
$req->addFile("image", $_FILES["image"]["tmp_name"], 'application/octet-stream');

#
#   Resolve the additional parameters required by the API   
#
$params = array();
foreach($_POST as $key => $val) {
    $params[$key] = $val;
}
$params["identity"] = $identity;

$params["timestamp"] = strtotime(date("Y-m-d H:m:s"));
$params["udid"] = $udid;
ksort($params);

$str = "";
foreach($params as $pst) {
    $str = $str . $pst;
}
$str .= $secret;

$hash = md5($str);

$params["authtoken"] = $hash;


#
#   Add the parameters to the request
#
foreach($params as $key => $val) {
    $req->addPostData($key, $val);
}


#
#   Finally, make the request.
#
$req->sendRequest();

#
#   redirect back to the referrer
#
@redirectToReferer();

/**
 * Redirect to a referring website if the HTTP_REFERER is set. Otherwise redirect to the HTTP_HOST.
 * @return 
 */
function redirectToReferer()
{
        
    if(isset($_SERVER["HTTP_REFERER"])){        
        header("Location: ". $_SERVER["HTTP_REFERER"]);
        exit(0);
    } else {
        header("Location: http://". $_SERVER["HTTP_HOST"]);
    }

}

Working with Comments

Retrieving a List of Comments

A list of comments is retrieved by making a GET request to the comments controller's index method, and specifying the result format. It is not necessary to explicitly state the index method in the GET request, the API will assume that a GET request should map to the index method when a post id is not included in the URI. The following examples demonstrate calls to the comments controller's index method:

http://api.shareitlive.com/1.0/comments.rss
http://api.shareitlive.com/1.0/comments.atom
http://api.shareitlive.com/1.0/comments.json
http://api.shareitlive.com/1.0/comments.plist

http://api.shareitlive.com/1.0/comments/index.rss
http://api.shareitlive.com/1.0/comments/index.atom
http://api.shareitlive.com/1.0/comments/index.json
http://api.shareitlive.com/1.0/comments/index.plist

Several parameters are supported in requests to the comments index controller.

count
Sets the number of records returned up to a maximum of 100. The default is 20. When used with the page parameter it is possible to paginate through multiple views of records.
page
Sets the page of results to return. When used with the count parameter it is possible to paginate through multiple views of records.
postId
Limits the results to comments of a specific post.

The result includes the total number of items matching the specified GET query. The total is defined as a category node in an ATOM or RSS formatted result, or as a more naturally occurring data point in a JSON or PLIST formatted result.

Retrieving a Single Comment

An individual comment is retrieved by making a GET request to the comments controller's show method and including the ID of the comment in the URI followed by the result format. It is not necessary to explicitly state the show method in the GET request, the API will assume that a GET request should map to the show method for the specified post ID. The following examples demonstrate calls to the comments controller's show method:

http://api.shareitlive.com/1.0/comments/10.rss
http://api.shareitlive.com/1.0/comments/10.atom
http://api.shareitlive.com/1.0/comments/10.json
http://api.shareitlive.com/1.0/comments/10.plist

http://api.shareitlive.com/1.0/comments/10/show.rss
http://api.shareitlive.com/1.0/comments/10/show.atom
http://api.shareitlive.com/1.0/comments/10/show.json
http://api.shareitlive.com/1.0/comments/10/show.plist

Creating a new Comment

A new comment is created by making a POST request to the comments controller's create method that includes the required parameters to create a new entry. A result format should not be specified for this call. It is not necessary to explicitly state the create method in the POST request, the API will assume that a POST request should map to the create method. You must be logged in via OpenID to create a comment. The following examples demonstrate calls to the comments controller's create method:

http://api.shareitlive.com/1.0/comments
http://api.shareitlive.com/1.0/comments/create

The following parameters are available for a call to the create method:

postId
(required) The id of the posting being commented upon.
content
(required) The text of the comment.

Editing an existing Comment

An comment may be edited (or flagged) by making either a POST or a PUT request to the comments controller's update method. If a PUT request is made, it is not necessary to specify the update method in the URI. If a POST request is made then the update method must be specified in the URI. The ID of the comment to update should be included in the request URI. A result format should not be specified for this call. You must be logged in via OpenID to make a call to update. The following examples demonstrate calls to the comments controller's update method:

(PUT) http://api.shareitlive.com/1.0/comments/10
(POST) http://api.shareitlive.com/1.0/comments/10/update

The following parameters are available for a call to the update method:

flag
(optional) Flags the comment as inappropriate. If flag is set then other parameters will be ignored.
content
(optional) The text of the comment. This will replace the previous text.

Deleting an existing Comment

An existing comment may be deleted by making either a POST or a DELETE request to the comments controller's delete method. If a DELETE request is made, it is not necessary to specify the delete method in the URI. If a POST is made then the delete method must be specified in the URI. The ID of the comment to delete should be included in the request URI. A result format should not be specified for this call. The following examples demonstrate calls to the comments controller's delete method:

(DELETE) http://api.shareitlive.com/1.0/comments/10
(POST) http://api.shareitlive.com/1.0/comments/10/delete

Copyright 2009 Oklahoma Publishing Company