要望があったので少し機能を追加しました。
追加機能：APIレスポンスデータのキャッシュ
wonderfl APIからのレスポンスデータを有効期限付きでローカルキャッシュします。
バージョンは0.2.0です。
wonderfl | RubyGems.org | your community gem host
・RDoc ドキュメント
wonderfl rdoc
使い方
[ruby]
#!/usr/bin/ruby
require ‘rubygems’
require ‘wonderfl’
# インスタンス生成時にキャッシュ情報を引数に与えます
# :cache_file でキャッシュファイル名を指定
# 指定しない場合は、’./wonderfl_cache.db’ ファイルが作成されます
# :expire でキャッシュの有効期限(秒)を設定
# 指定しない場合は 0 (秒)で設定されます
client = Wonderfl::Client.new(‘your api_key’,
:cache_file => ‘cache.db’,
:expire => 60*10)
[/ruby]
その他に変更されたインタフェースはありません。
wonderflのAPIサーバはそんなに強くない印象があるので優しく使おう。ということでキャッシュ機能(有効期限を指定可能)を付けました。指定したファイル(指定しない場合は’./wonderfl_cache.db’)にデータがキャッシュされます。キャッシュが邪魔な時はそのファイルを削除するだけでOKです。
内部でPStoreを利用しているので、別のプログラムからキャッシュファイルを読み込んで操作することもできます。キャッシュのキーはURI、例えば ‘/user/wellflat’ や ‘/code/3t6r/forks’ のようになっています。
今回の機能追加でやっと利用価値が出てきたかなといったところでしょうか。。
(ここまで追記)
———————————————————————
wonderfl APIをRubyから簡単に利用するためのライブラリを作りました。
Rubygemsに公開されています。
wonderfl | RubyGems.org | your community gem host
・RDoc ドキュメント
(Wonderfl::Client の所を見れば使い方は分かります)
File: README.rdoc [RDoc Documentation]
wonderfl APIの現在の仕様として、、リソースが存在しなくても、認証に失敗しても、全てHTTPステータスコード 200を返却してくるまずい仕様なので(せっかくリソース指向になってるのに；)、異常系処理を書いてる時に困った人も多いかと思います。このライブラリではAPIのエラー内容に応じた例外を投げるようにしています。それ以外は薄いラッパーなのでキャッシュ機能などは備えておらず (キャッシュ機能追加しました)、JSONレスポンスを解析する程度しか内部では行っていません。
導入方法
gemを利用してインストールできます。
$ gem install wonderfl
また、このライブラリを利用するにはapi keyが必要です。
wonderfl build flash onlineにて作成しておきます。
使い方
詳細はRubygemsのページから辿れます。RDocも適宜参照してください。
基本的に Wonderfl::Client クラスの各メソッドを呼ぶだけです。
- Wonderfl::Client
- get_user(‘user name’)
- get_user_codes(‘user name’)
- get_code(‘code id’)
- get_code_forks(‘code id’)
[ruby]
#!/usr/bin/ruby
require ‘rubygems’
require ‘wonderfl’
begin
# Wonderfl::Client オブジェクトを生成、引数にapi key
client = Wonderfl::Client.new(‘your api key’)
client.api_key = ‘your api key’ # 後でapi keyを設定することも可能
# ユーザー情報を取得、引数にユーザー名
user = client.get_user(‘wellflat’) #=> Wonderfl::User
# 各ユーザー情報を参照
puts user.icon #=> “http://wonderfl.net/img/comon/~.gif”
puts user.external_url #=> “https://rest-term.com/”
puts user.name #=> “wellflat”
puts user.description #=> “web engineer”
# 作品情報を取得、引数にコードID
code = client.get_code(‘code id’) #=> Wonderfl::Code
# 作品の各情報を参照
puts code.thumbnail #=> 作品のサムネイルURL
puts code.forked_count #=> forkされた数
puts code.favorite_count #=> favoriteされた数
puts code.title #=> 作品のタイトル
puts code.as3 #=> 作品のAS3.0コード (巨大なコードもあるので注意)
… # 他にもいろいろな情報を取得できます
# ユーザーの投稿した作品情報を取得
user_codes = client.get_user_codes(‘user name’) #=> Wonderfl::UserCodes
# ユーザーの投稿した作品数
puts user_codes.count
# 作品のタイトルを列挙
user_codes.each do |code|
puts code.title #=> title 以外でももちろんOK
end
# forkされた作品情報を取得
code_forks = client.get_code_forks(‘code id’) #=> Wonderfl::CodeForks
# forkされた作品数
puts code_forks.count
# forkしたユーザーの名前を列挙
code_forks.each do |code|
puts code.user_name
end
rescue Wonderfl::BadRequest => e
# 各メソッドの引数が不正な場合
rescue Wonderfl::Unauthorized => e
# 認証に失敗した場合 (api keyが不正)
rescue Wonderfl::NotFound => e
# 指定したユーザーや作品が存在しない場合
rescue Wonderfl::InternalServerError => e
# wonderfl APIがレスポンスを正しく返却できない場合
# (APIの仕様変更などによりJSONレスポンスが解析不可の場合も)
end
[/ruby]
コードを見てもらえば分かるように、各エラー内容に応じた例外が発生するようになっているのでそれぞれに対応した異常系処理を書くことが簡単になります。また、取得した情報が数値なら(forked_count 等) Integer 型、日付なら(created_date 等) Time 型に内部で変換しています。
また、現在取得できるユーザー/作品情報について載せておきます。
・ユーザー情報 (Wonderfl::User)
- icon
- external_url
- name
- description
・作品情報 (Wonderfl::Code)
- thumbnail
- as3 (get_user 利用時のみ参照可)
- parent
- modified_date (get_user 利用時のみ参照可)
- compile_ok
- created_date
- forked_count (get_user 利用時のみ参照可)
- license
- swf
- diff (get_user 利用時のみ参照可)
- user_icon (get_user_codes, get_code_forks 利用時に参照可)
- user_name (get_user_codes, get_code_forks 利用時に参照可)
- title
- id
- favorite_count (get_user 利用時のみ参照可)
注意事項
BANされないように、取得結果をキャッシュしつつ利用するといいです（このライブラリにキャッシュ機能を付けることも考えています）(キャッシュ機能追加しました)。あと、要望や不具合などがあったらお知らせください。
実は、このライブラリはけっこう昔に作ったものなので、スコアAPIのクライアントは備えていません（要望があれば追加します）。APIの仕様が運良くまだ変わってないようなので今も動作しているだけだったりします。。（不具合があれば修正します）
gemのライブラリを作った個人的な目的としては、gitに慣れることとRSpecの書き方を学ぶことの2つがありました。会社ではバージョン管理にsubversionを使っていてgitを使う機会がなかったので。RSpecについては、振る舞い駆動開発というものを体験しておく必要性を感じたからです。どちらもある程度理解することはできたので目的は達成したかなと思います。rakeの使い方にも慣れるという嬉しい副産物も(^^
また、Flash使いの人はサーバサイドの言語にPHPを選択する人がほとんどだと思いますが、Rubyが使えるとRailsアプリケーションと連携したりと作品の幅が広がるのでオススメです。