NAME
WWW::ThisIsMyJam - Synchronous and asynchronous interfaces to This Is My
Jam
SYNOPSIS
use WWW::ThisIsMyJam;
my $jam = WWW::ThisIsMyJam->new;
$jam->person('jamoftheday');
Description
This module provides access to Jam data through the new, official API in
synchronous or asynchronous mode.
The asynchronous mode requires you have AnyEvent and AnyEvent::HTTP
available. However, since it's just *supported* and not *necessary*, it
is not declared as a prerequisite.
Methods
This Is My Jam provides an ultra simple, JSON-based API. First, we'll
cover public utility methods and then the categorized Jam functions.
Standard
new( )
Creates a new WWW::ThisIsMyJam object.
# typical usage
my $jam = WWW::ThisIsMyJam->new;
# it would be pointless to change these, but it's possible
my $jam = WWW::ThisIsMyJam->new(
apiversion => 1,
basename => 'http://api.thisismyjam.com'
);
Person
Person methods cover a single user.
user( person )
A user's overview data includes all information about the requested
person along with their current jam (if any). All methods require at
least a username.
# Fetch info for the Jam of the Day account
my $overview = $timj->user( 'jamoftheday' );
# Use callbacks for a specific user
$timj->user( 'jamoftheday', { cb => sub { my ( $overview ) = @_; ... } });
likes( person )
Returns a list of liked jams. Takes the optional parameter 'show', which
specifies whether to include only current or past (expired) jams.
# Get jams I like
$timj->likes( 'jamoftheday' );
# Only get active jams
$timj->likes({ person => 'jamoftheday', show => 'current' });
# Only get expired jams
$timj->likes({ person => 'jamoftheday', show => 'past' });
jams( person )
Returns a list of the person's jams. Optional parameter 'show' can be
set to only show past (expired) jams.
# Get all of a user's jams
$timj->jams({ person => 'jamoftheday' });
# Only get (expired) jams from the past
$timj->jams({ person => 'jamoftheday', show => 'past' });
following( person )
Returns a list of people that a particular person is following. Optional
parameter 'order' can be set to sort the users: "order =>
'followedDate'" orders by date followed; "order => 'affinity'" currently
orders by number of likes from the requested person; "order => 'name'"
orders by name alphabetically.
While omitted from the official documentation, observation indicates
that 'affinity' is the default order.
# Get users the person if following
$timj->following({ person => 'jamoftheday' });
# Get users the person is following sorted by name
$timj->following({ person => 'jamoftheday', order => 'name' });
followers( person )
Returns a list of people that a particular person is followed by.
Optional parameter 'order' can be set to sort the users: "order =>
'followedDate'" orders by date followed; "order => 'affinity'" currently
orders by number of likes from the requested person; "order => 'name'"
orders by name alphabetically.
While omitted from the official documentation, observation indicates
that 'affinity' is the default order.
# Get users the person if following
$timj->followers({ person => 'jamoftheday' });
# Get users the person is following sorted by name
$timj->followers({ person => 'jamoftheday', order => 'name' });
follow( person )
Follow the specified user. Requires authentication.
# Follow someone
$timj->follow({ person => 'jamoftheday' });
unfollow( person )
Unfollow the specified user. Requires authentication.
# Unfollow someone
$timj->unfollow({ person => 'jamoftheday' });
Jam
Jam methods return metadata about a single or list of jams.
jam( id )
Retrieves information on a single jam by ID.
# Get info about a jam. (Jam of the Day from March 6th, 2013)
$timj->jam( { id => '4zugtyg' });
likers( id )
Returns a list of the people who liked a particular jam.
# Get a list of people who liked the Jam of the Day from March 6th, 2013
$timj->likers( { id => '4zugtyg' });
Note: "likers" isn't a word. I may change the name of this method before
v1.0.0.
comments( id )
Returns a list of the comments that have been added to a jam.
# What you say?
$timj->comments({ id => '4zugtyg' });
related( id )
Returns a list of jams that may be related (musically or otherwise) to
the specified jam. Only works on active jams and not to be confused with
"related_jams( username )".
# All of these things are just like the other
$timj->related({ id => '5sd5q1b' });
like( id )
Like a jam. You can only like jams that are currently active. Requires
authentication.
$timj->like({ id => '4zugtyg' });
unlike( id )
Unlike a jam. You can only unlike jams that are currently active.
Requires authentication.
$timj->like({ id => '4zugtyg' });
post_comment( id, comment )
Post a new comment on a jam. Requires authentication.
# Add nothing to the conversation
$timj->post_comment({ id => '4zugtyg', comment => '+1' });
rejammers( id )
Returns a list of people who rejammed this jam.
# Find *true* fans of this jam
$timj->rejammers({ id => '4zugtyg' });
Comments
get_comment( id )
Retrieve a single comment by ID.
# What's the story, morning glory?
$timj->delete_comment({ id => 'q0hdq3' });
delete_comment( id )
Delete a single comment. Only the author of the comment and the person
who posted the jam can delete it. Requires authentication.
# Quiet, you!
$timj->delete_comment({ id => 'q0hdq3' });
Explore
popular_jams( )
Returns a list of today's most loved jams.
$timj->popular_jams();
trending_jams( )
Returns a list of songs getting a lot of recent attention.
$timj->trending_jams();
rare_jams( )
Returns a list of tracks we don't hear that often.
$timj->rare_jams();
random_jams( )
Returns a random list of current jams.
$timj->random_jams();
newbie_jams( )
Returns a list of jams from people who have just joined This Is My Jam.
$timj->newbie_jams();
related_jams( username )
A list of jams related to username's current jam. Easily but not to be
confused with "related( id )".
# Grab jams related to the current Jam of the Day
$timj->related_jams({ username => 'jamoftheday' });
Yes, I know the person vs. username inconsistency. Blame This Is My
Jam's API designers or forget it and just use the short method call:
# Same as above but less confusing
$timj->related_jams( 'jamoftheday' );
Search
Search methods return lists of related material. With great power...
search_jams( by, q )
Searching by artist will return jams by or similar to the requested
artist. Genre search is powered by Last.fm tag search. Hashtag support
is experimental (no pagination, might be slow so use the asynchronus
interface).
# Find jams similar to those by The Knife
$timj->search_jams({ by => 'artist', q => 'the knife' });
# Find electronica jams
$timj->search_jams({ by => 'genre', q => 'electro' });
# Find jams with descriptions containing #jolly hashtags
$timj->search_jams({ by => 'hashtag', q => 'jolly' }); # Note missing #
search_people( by, q )
You can either search for people by name, artist and track. Searching by
name returns people with the search string in their username, full name
or Twitter name. Searching by artist returns people who have posted
tracks by artists (fuzzy) matching the search string. Searching by track
returns people who have posted a particular track (strict,
case-insensitive matching).
# Find users with the word 'jam' in their name, username, twitter handle
$timj->search_people({ by => 'name' , q => 'jam' });
# Find users who jam out to music by The Beach Boys
$timj->search_people({ by => 'artist', q => 'beach boys' });
# Find users who jam out to 'Video Games' by Lana del Rey
$timj->search_people({ by => 'track', q => 'Lana del Rey|Video games' });
Miscellaneous
verify( )
Returns information about the currently authenticated user.
# Eh?
$timj->verify();
API Methods and Arguments
Most This Is My Jam API methods take parameters. All WWW::ThisIsMyJam
API methods will accept a HASH ref of named parameters as specified in
the This Is My Jam API documentation. For convenience, many
WWW::ThisIsMyJam methods accept simple positional arguments. The
positional parameter passing style is optional; you can always use the
named parameters in a HASH reference if you prefer.
You may pass any number of required parameters as positional parameters.
You *must* pass them in the order specified in the documentation for
each method. Optional parameters must be passed as named parameters in a
HASH reference. The HASH reference containing the named parameters must
be the final parameter to the method call. Any required parameters not
passed as positional parameters, must be included in the named parameter
HASH reference.
For example, the method "following" has one required parameter,
"person". You can call "following" with a HASH ref argument:
$timj->following({ person => 'jamoftheday' });
Or, you can use the convenient, positional parameter form:
$timj->following('jamoftheday');
The "following" method also has an optional parameter: "order". You must
use the HASH ref form:
$timj->following({ person => 'jamoftheday', order => 'name' });
You may use the convenient positional form for the required "person"
parameter with the optional parameters specified in the named parameter
HASH reference:
$timj->following('jamoftheday', { order => 'name' });
Convenience form is provided for the required parameters of all API
methods. So, these two calls are equivalent:
$timj->search_jams({ by => 'artist', q => 'Stone Roses' });
$timj->search_jams('artist', 'Stone Roses');
This scheme is ripped directly from Net::Twitter.
Paging
Some methods return partial results a page at a time, currently 60 items
per page. For these, there is an optional "page" parameter. The first
page is returned by passing "page => 1", the second page by passing
"page => 2", etc. If no "page" parameter is passed, the first page is
returned. Each paged response contains a "list" HASH ref with a
"hasMore" key. On the last page, "hasMore" will be "false".
Here's an example that demonstrates how to obtain all of a user's
previous jams in a loop:
my @jams;
for (my $page = 1;; ++$page) {
my $r = $timj->jams({person => 'jamoftheday', page => $page});
push @jams, @{$r->{jams}};
last unless $r->{list}{hasMore};
}
Asynchronus Callbacks
The supported asynchronous mode requires an additional parameter "cb".
This must be a CODE ref and works like so:
$timj->verify({ cb => sub { ... } });
$timj->jams( 'jamoftheday', { cb => sub { ... } });
$timj->like({ id => '4zugtyg', cb => sub { ... } });
This is ripped directly from Net::xkcd.
Authentication
In order to perform actions on behalf of a user such as liking a jam or
following people, a user first needs to give permission to your app.
Once that's been done, you can make authenticated calls.
This Is My Jam uses OAuth 1.0 for authentication. Before v1.0.0,
WWW::ThisIsMyJam will support OAuth.
Dependencies
* Try::Tiny
* HTTP::Tiny
* JSON::Tiny
* Carp
* URI
* URI::QueryParam
* Moo
* Type::Tiny
Optional Dependencies
* AnyEvent
* AnyEvent::HTTP
See Also
* Net::Twitter
* Net::xkcd
* This Is My Jam API Documentation
Bug Reports
If email is better for you, my address is mentioned below but I would
rather have bugs sent through the issue tracker found at
http://github.com/sanko/www-thisismyjam/issues.
Author
Sanko Robinson - http://sankorobinson.com/
CPAN ID: SANKO
License and Legal
Copyright (C) 2013 by Sanko Robinson
This program is free software; you can redistribute it and/or modify it
under the terms of The Artistic License 2.0
. See the LICENSE
file included with this distribution or notes on the Artistic License
2.0 for
clarification.
When separated from the distribution, all original POD documentation is
covered by the Creative Commons Attribution-Share Alike 3.0 License
. See the
clarification of the CCA-SA3.0
.