diff options
Diffstat (limited to '')
| -rw-r--r-- | posts/2010-06-10-moosex-net-api-update.org | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/posts/2010-06-10-moosex-net-api-update.org b/posts/2010-06-10-moosex-net-api-update.org new file mode 100644 index 0000000..f130447 --- /dev/null +++ b/posts/2010-06-10-moosex-net-api-update.org @@ -0,0 +1,151 @@ +[[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]]). |