1 files changed, 137 insertions, 0 deletions
diff --git a/posts/2009-12-20-moosex-net-api.org b/posts/2009-12-20-moosex-net-api.org
new file mode 100644
index 0000000..4d90494
--- /dev/null
+++ b/posts/2009-12-20-moosex-net-api.org
@@ -0,0 +1,137 @@
+** Net::Twitter
+
+I've been asked for [[http://linkfluence.net][$work]] to write an API
+client for [[http://www.backtype.com/][backtype]], as we plan to
+integrate it in one of our services. A couple of days before I was
+reading the
+[[http://search.cpan.org/perldoc?Net::Twitter][Net::Twitter]] source
+code, and I've found interesting how
+[[http://blog.questright.com/][semifor]] wrote it.
+
+Basically, what Net::Twitter does is this: for each API method, there is
+a =twitter_api_method= method, where the only code for this method is an
+API specification of the method. Let's look at the public timeline
+method:
+
+#+BEGIN_SRC perl
+    twitter_api_method home_timeline => (
+        description => <<'',
+    Returns the 20 most recent statuses, including retweets, posted by the
+    authenticating user and that user's friends. This is the equivalent of
+    /timeline/home on the Web.
+
+        path     => 'statuses/home_timeline',
+        method   => 'GET',
+        params   => [qw/since_id max_id count page/],
+        required => [],
+        returns  => 'ArrayRef[Status]',
+    );
+#+END_SRC
+
+The =twitter_api_method= method is exported with Moose::Exporter. It
+generates a sub called =home_timeline= that is added to the class.
+
+** MooseX::Net::API
+
+As I've found this approch nice and simple, I thought about writing a
+[[http://git.lumberjaph.net/p5-moosex-net-api.git/][little framework]]
+to easily write API client this way. I will show how I've write a
+[[http://git.lumberjaph.net/p5-net-backtype.git/][client for the
+Backtype API]] using this (I've wrote some other client for private API
+at works too).
+
+** Backtype API
+
+First we defined our class:
+
+#+BEGIN_SRC perl
+    package Net::Backtweet;
+    use Moose;
+    use MooseX::Net::API;
+#+END_SRC
+
+MooseX::Net::API export two methods: =net_api_declare= and
+=net_api_method=. The first method is for all the paramters that are
+common for each method. For Backtype, I'll get this:
+
+#+BEGIN_SRC perl
+    net_api_declare backtweet => (
+        base_url    => 'http://backtweets.com',
+        format      => 'json',
+        format_mode => 'append',
+    );
+#+END_SRC
+
+This set
+
+-  the base URL for the API
+-  the format is JSON
+-  some API use an extension at the name of the method to determine the
+   format. "append" do this.
+
+Right now three formats are supported: xml json and yaml. Two modes are
+supported: =append= and =content-type=.
+
+Now the =net_api_method= method.
+
+#+BEGIN_SRC perl
+    net_api_method backtweet_search => (
+        path     => '/search',
+        method   => 'GET',
+        params   => [qw/q since key/],
+        required => [qw/q key/],
+        expected => [qw/200/],
+    );
+#+END_SRC
+
+-  path: path for the method (required)
+-  method: how to acces this resource (GET POST PUT and DELETE are
+   supported) (required)
+-  params: list of parameters to access this resource (required)
+-  required: which keys are required
+-  expected: list of HTTP code accepted
+
+To use it:
+
+#+BEGIN_SRC perl
+    my $backtype = Net::Bactype->new();
+    my $res =
+        $backtype->backtweet_search(q => "http://lumberjaph.net", key => "foo");
+    warn Dump $res->{tweets};
+#+END_SRC
+
+** MooseX::Net::API implementation
+
+Now, what is done by the framework. The =net_api_declare= method add
+various attributes to the class:
+
+-  api\_base\_url: base URL of the API
+-  api\_format: format for the query
+-  api\_format\_mode: how the format is used (append or content-type)
+-  api\_authentication: if the API requires authentication
+-  api\_username: the username for accessing the resource
+-  api\_password: the password
+-  api\_authentication: does the resource requires to be authenticated
+
+It will also apply two roles, for serialization and deserialization,
+unless you provides your own roles for this. You can provides your own
+method for useragent and authentication too (the module only do basic
+authentication).
+
+For the =net_api_method= method, you can overload the authentication (in
+case some resources requires authentication). You can also overload the
+default code generated.
+
+In case there is an error, an MooseX::Net::API::Error will be throw.
+
+** Conclusion
+
+Right now, this module is not finished. I'm looking for suggestions
+(what should be added, done better, how I can improve stuff, ...). I'm
+not aiming to handle all possibles API, but at least most of the REST
+API avaible. I've uploaded a first version of
+[[http://search.cpan.org/perldoc?MooseX::Net::API][MooseX::Net::API]]
+and [[http://search.cpan.org/perldoc?Net::Backtype][Net::Backtype]] on
+CPAN, and [[http://git.lumberjaph.net/p5-net-backtype.git/][the code]]
+is also [[http://git.lumberjaph.net/p5-moosex-net-api.git/][available on
+my git server]].