NAME

WebService::HackerNews - interface to the official HackerNews API

SYNOPSIS

 use WebService::HackerNews;
 my $hn     = WebService::HackerNews->new;
 my @top100 = $hn->top_story_ids;
 my $item   = $hn->item( $top100[0] );
 my $user   = $hn->user($item->by);

 printf qq{"%s" by %s (karma: %d)\n},
        $item->title, $item->by, $user->karma;

DESCRIPTION

This module provides an interface to the official Hacker News API. This is very much a lash-up at the moment, and liable to change. Feel free to hack on it and send me pull requests.

It provides a semi object-oriented interface to the API. You start off by creating an instance of WebService::HackerNews:

 $hn = WebService::HackerNews->new;

You can then call one of the methods to either get information about items or users.

An item is either a story, a job, a comment, a poll, or a pollopt. All items live in a single space, and are identified by a unique integer identifier, or id. Given an id, you can get all information for the associated item using the item() method.

A user is like an item, but represents a registered user of HackerNews. The id for a user isn't an integer, but is a username. Given a username, you can get all information for the associated user with the user() method.

Items and User are represented with classes, but where the attributes of items and users relate to further items and classes, they are represented as references to arrays of ids, rather than returning references to arrays of other objects.

METHODS

As of version 0.02, this implements all of the functions listed in the official documentation for the API.

top_story_ids

Returns a list of ids for the current top 100 stories.

 my @ids = $hn->top_story_ids;

You can then call item() to get the details for specific items.

item($ID)

Takes an item id and returns an instance of WebService::HackerNews::Item, which has attributes named exactly the same as the properties listed in the official doc.

 $item = $hn->item($id);
 printf "item %d has type %s\n", $item->id, $item->type;

user($ID)

Takes a user id and returns an instance of WebService::HackerNews::User, which has attributes named exactly the same as the user properties listed in the official doc.

 $user = $hn->user($username);
 printf "user %s has %d karma\n", $user->id, $user->karma;

max_item_id

Returns the max item id.

changed_items_and_users

Returns two array references, which contain IDs for changed items and usernames for changed users:

 use WebService::HackerNews 0.02;

 my $hn              = WebService::HackerNews->new;
 my ($items, $users) = $hn->changed_items_and_users;

 process_changed_items(@$items);
 process_changed_users(@$users);

This method returns "recently changed items and users", without defining 'changed since when?'. If you want to track changes, you'd just have to poll on a regular basis.

This method is really aimed at people using Firebase streaming API.

This method was added in version 0.02, so you should specify that as the minimum version of the module, as above.

SEE ALSO

Blog post about the API.

API Documentation.

REPOSITORY

https://github.com/neilb/WebService-HackerNews

AUTHOR

Neil Bowers <neilb@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Neil Bowers <neilb@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm WebService::HackerNews

perl -MCPAN -e shell
install WebService::HackerNews