[[http://git.lumberjaph.net/p5-moosex-net-api.git/][MooseX::Net::API]]
is a module to help writing clients for RESTful (and even non-RESTful)
WebServices:
#+BEGIN_SRC perl
package my::api;
use MooseX::Net::API;
net_api_declare myapi => (
api_base_url => 'http://api....',
api_format => 'json',
);
net_api_method users => (
method => 'GET',
path => '/users/:country',
description => 'fetch a list of users',
params => [qw/country/],
expected => [qw/200 404/],
);
#+END_SRC
We've been using this module at work for the last few months on various
internal APIs, and I'm pretty pleased with the result so far.
Lately I've started to rework the core. I've tried to split most of the
functionalities into roles, and rework the code that generates the
various methods. I've also added methods to access miscellaneous
information :
#+BEGIN_SRC perl
my $client = my::api->new;
# to get a list of API methods
$client->meta->get_all_net_api_methods();
# find an API method
my $method = $client->meta->find_net_api_method_by_name('users');
# and now informations about the method
say $method->documentation;
name: users
description: fetch a list of useres
method: GET
path: /users/:country
arguments: country
expected: 200, 404
#+END_SRC
It's not yet complete, but a new version will be available soon on CPAN.
Here is a list of some more features I plan to add quickly:
- better internal API
- better authorization support (OAuth!)
- add more methods to provide better introspection
- better unserialization
- more tests and better documentation
- generate POD via a PODWeaver plugin ?
- plugins ?
- renaming ? (not sure it really fits in the MooseX:: namespace)
** http-console
I've also started
[[http://git.lumberjaph.net/p5-net-http-console.git/][Net::HTTP::Console]].
It's inspired by
[[http://github.com/cloudhead/http-console][http-console]]. It relies on
MX::Net::API, and can use any libraries written with MX::Net::API, as
well as any *raw* RESTful API. As an example, let's use it on twitter.
#+BEGIN_EXAMPLE
% http-console --url http://api.twitter.com --format json
http://127.0.0.1:5984> GET /1/statuses/public_timeline
[
{
"source" : "web",
"favorited" : false,
"geo" : null,
"coordinates" : null,
"place" : null,
...
}
]
http://127.0.0.1:5984> show headers
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0
last-modified: Mon, 07 Jun 2010 15:27:12 GMT
x-transaction: 1275924432-94882-31146
x-ratelimit-reset: 1275925258
...
#+END_EXAMPLE
You can call any method from the twitter API (at the exception of the
ones that require authentication: it's not supported yet).
You can also use it with any library that uses MX::Net::API:
#+BEGIN_EXAMPLE
% http-console --lib Net::Backtweet
http://api.backtweet.com> help command
available commands:
- tweets\_by_url
- stats\_by_url
- good\_tweets_by_url
http://api.backtype.com> help command tweets\_by_url
name: tweets_by_url
description: Retrieve tweets that link to a given URL, whether the links are shortened or unshortened.
method: GET
path: /tweets/search/links
http://api.backtype.com> stats\_by_url {"q":"http://lumberjaph.net","key":s3kr3t"}
{
"tweetcount" : 388
}
#+END_EXAMPLE
Arguments to the methods are serialized in JSON format. Not sure if it's
the best idea I will see if it needs improvement while using it. You can
also perform POST and PUT with content.
#+BEGIN_EXAMPLE
http://localhost:5984> POST /test_rtgi_fetcher {"foo":"bar"}
{
"ok" : true,
"rev" : "1-fe67006eb0e02e5f0057b5b2a6672391",
"id" : "fe3175615a34eb28153479307c000f26"
}
#+END_EXAMPLE
It's far from being complete at the moment, but I will extend it
quickly. Right now, you can define global headers, and get help for all
methods in your MX::Net::API library. Authentication is on top of my
priority list, as is alias creation, so instead of doing (on a
non-moosex::net::api lib): =GET /users/= you will do:
#+BEGIN_QUOTE
alias users/:country as users
#+END_QUOTE
then:
#+BEGIN_QUOTE
users {"country":"france"}
#+END_QUOTE
(and yes, I've switched from wordpress to
[[http://github.com/perigrin/blawd][blawd]]).
