Apr 5, 2011

Forrst API Pull Tutorial — Pt. 1

Forrst.com has become a community of over 23000 Developers and Designers in only a few months, and this tutorial will teach you how to use a simple Forrst API call to grab the public data for a forrst user.
As of March 2011 this still works, but may change as their API is still being developed. We will use a simple PHP get file contents call to grab the JSON data, and then convert that into a useful PHP array, which in turn will be used to generate a simple html display.

Getting Started

You can use this to generate your own pages with your Forrst data or perhaps a useful application for Forrst users.
There will be a lot more to come in the full API release, but you’ll have to ask Kyle Bragger about that.

Clicking the above image will take you to a demo using the code explained below.

Resources

Active Usernames from Forrst by forsst.com

file_get_contents in PHP by PHP.net

json_decode in PHP by PHP.net

How to get Forrst user data

At this time the Forrst API does not have a search functionality, so this will only work with exact username matches.
For the demo I started it with my own, but you can type in any other valid username and see their info as well.

In order to grab the json data we are using a simple PHP function:

function forrst_user($username){
    $userdata = file_get_contents("http://api.forrst.com/api/v2/users/info?username=".$username);
    // We use json_decode to put the data into an array.
    //Note: json_decode only work in PHP5+ and the module must be installed in apache on your server.
    $data = json_decode($userdata, true);
    $user = $data['resp'];
    if($data['stat']=='ok') return $user;
    else{
        if($data['stat']=='fail'){
            return array('error'=>$data['error']);
        }else{
            //There could be additional statuses returned in the future
        }
    }
}

This function uses two built-in php functions “get_file_contents” and “json_decode” to do the hard work for you. The first one grabs the data via the API URL provided by Forrst.
The second converts the returned data into useful PHP arrays. Note: json_decode only work in PHP5.2+ and the module must be installed in apache on your server.

The Data Returned:

The API call returns a block of data, which when converted into arrays contains the following information:

$user['id'] : The Forrst ID #
$user['username'] : The Username.
$user['name'] : The Name.
$user['url'] : The Profile URL for the User.
$user['posts'] : The # of Posts Created by the User on Forrst.
$user['comments'] : The # of Comments made by the User on Forrst Posts.
$user['likes'] : The # of Likes made by the User on Forrst Posts.
$user['followers'] : The # of people following this User.
$user['following'] : The # of people followed by this User.
$user['photos'] : Array of all the images stored for this user on Forrst.
- [xl_url] (200px by 200px)
- [large_url] (150px by 150px)
- [medium_url] (75px by 75px)
- [small_url] (45px by 45px)
- [thumb_url] (25px by 25px)
$user['in_directory'] : 1 meaning the user is in the forrst directory and 0 if they are not.
$user['tag_string'] : comma delimited string of tags the user finds themselves interested in.

At the time of this writing there are additional fields being returned that may later on be used for proper authentication as there is currently no authentication to pull this data.

These fields are:

$data['stat'] : Returns the status of the response. “ok” if the request succeeded. “fail” in case of an error.
$data['in'] : Returns the time it took to execute the request in seconds.
$data['authed'] : Currently returns empty or “false”. This field tells us if the request was authorized.
$data['authed_as'] : Currently returns empty or “false”. This field will most likely tell us in the future which API user made the request.
$data['env'] : Currently just returns “prod” (As in Production Environment) This fields is probably more useful to the Forrst Devs than to us.
In case of failure: $data['error'] : Contains the textual Error Message returned by the API

Data/Display Manipulation

To display the data in the demo I used some basic html to just output the data to the screen, including basic usage of all the returned user data.
The great thing is that once you have the data array, you can essentially do anything you want with it.
Below follows a display example of the results.

</pre>
<pre><body>
<div id="wrapper">
 <form action="" method="post">
 <h1>Find Posts for a Forrst User:</h1><br />
 Enter Username: <input type="text" name="username" size="25" value="'.strip_tags(trim($_POST['username'])).'"/> <input type="submit" name="irrelevant" value="Go!" />
 </form>
';
if(!$_POST['username']){
 $u = get_forrst_posts('crassiusneo');
 $_POST['username']='crassiusneo';
 echo '
 <div id="result">
 Hi, This script will grab the public posts for a Forrst User.<br /><br />
 It does not use the API as that functionality is not yet available to us.<br /><br />
 You can generate a neat custom profile if you combine this script with the previous tutorial at:<br />
 <a href="http://www.webnuz.com/tutorials/03-27-2011_Forrst_API_Tutorial">http://www.webnuz.com/tutorials/03-27-2011_Forrst_API_Tutorial</a>
 <br /><br />
 Below are the Posts grabbed from my own Posts page, but type in a Username above and you can grab theirs too.<br />
 A View Link is not yet possible because Forrst uses a controller to generate a unique link for each post, so that will have to wait for the official Forrst API release.
 </div>';
}else{
 $u = get_forrst_posts($_POST['username']);
}
if(isset($u['error']) || $u==''){
 if($u=='') $u['error']='Not Found.';
 echo '<p>Your request for data about username: <strong>'.$_POST['username'].'</strong> failed. Reason: <strong>'.$u['error'].'</strong></p>';
}else{
 if(count($u)>0){
 echo '<div id="result">
 <h1><strong>Posts for '.$_POST['username'].'</strong>.</h1>
 </div>';
 foreach ($u as $p){
 echo '
 <div id="result">
 <p>
 <span>'.$p['posted'].'</span>
 <h1>'.$p['title'].'</h1>
 <div></div>
 <span>'.$p['subtitle'].'</span><br />
 '.$p['description'].'
 </p>
 </div>';
 }
 echo '
 <div id="result">
 <p>
 You can check out the Forrst profile at:<br /> <a href="http://forrst.me/'.$_POST['username'].'" target="_blank">http://forrst.me/'.$_POST['username'].'</a>.<br />
 You can check view the Forrst Posts page at:<br /> <a href="http://forrst.me/'.$_POST['username'].'/posts" target="_blank">http://forrst.me/'.$_POST['username'].'/posts</a>.<br />
 </p>
 </div>';
 }
}
echo '
 <div>
 <a href="http://www.webnuz.com/tutorials/04-03-2011_Forrst_API_Grab_User_Posts/source.txt" target="_new">Click here to View the source</a><br />
 </div>
</body></pre>
<p>

Some CSS

html, body{ width:100%; height:100%; padding:0; margin:0; font-size:12px; font-family: arial, helvetica; background:#162810;}
#wrapper{width:800px; margin:0 auto; padding:20px; background:#EBE9DB; }
.with_bg{ padding:10px; background:#F7F7F7;}
form {width:400px; margin:0 auto; }
h1{ color:#3B3227; }
#result{ width:400px; margin:20px auto; }

Conclusion

The Forrst API is still in its infancy and at this time you can only do some basic requests, but we know they are working on releasing a full version soon that should have a lot more functionality.
For now, I hope this tutorial just gave you an idea of what sort of data you will be able to expect from the Forrst API, and also showed you how you can use a little bit of code to process and display the data returned by the API.

The full PHP/HTML/CSS source is available here: Here