JSON-RPC, RESTful API とクエリパラメータ
OpenSocial の JSON-RPC, RESTful API の設計についてのよもやま話です。
JSON-RPC とクエリパラメータ
OpenSocial Core API Server Specification 1.1 に URL Addression と言うセクションがあります。
これは JSON-RPC を http GET で呼び出す際に params の部分など構造化されたデータをどうやって渡すのって際の仕様になります。
| JSON Object | URL Parameter | ||
| { "field" : "value" } | field=value | ||
| { "field" : [1,2,3,4,5]} | field=1,2,3,4,5 | ||
| { "field" : "12" } | field='12' | ||
| { "field" : [identifier,anotheridentifier]} | field=identifier,anotheridentifier | ||
| { "field" : ["value","another value"]} | field=value,"another value" | ||
| { "field" : ['value','another value']} | field=value,'another value' | ||
| { "field" : { "nested" : "value" }} | field.nested=value | ||
| { "field" : [{ "nested1" : "value1" }, { "nested2" : "value2" }]} | field(0).nested1=value1&field(1).nested2=value2 |
まぁシングルクオートとダブルクオートを意図的に使い分けたいユースケースがさっぱり意味が分からない上に、identifier とか意味分かんないんでこの辺り謎過ぎるのですが、そういう細かい突っ込みはとりあえず置いておきます。
ところで JSON-RPC 2.0 の extension として定義されている JSON-RPC over HTTP によれば、GET の時の挙動は3.5 GET に書いてあり、params の部分はエンコードしろと書いてあります。どういう風にエンコードするかと言えば Base64 して URL Encode しろと言う感じです。
Pre-Encoded Params:
http://<end point>?method=sum¶ms={"a":3,"b":4}&id=2
http://<end point>?method=sum¶ms=[3,4]&id=1
Encoded Request:
http://<end point>?method=sum¶ms=eyJhIjozLCJiIjo0fQ%3D%3D&id=2
http://<end point>?method=sum¶ms=WzMsNF0%3D&id=1って感じ。これはこれで単純明快ですね。
ちなみに先に JSON-RPC に対して結論を言っておくと、誰が楽しくて GET で叩くのか僕には意味が分かりません！*1大人しく POST 使いましょう。
RESTful API とクエリパラメータ
それでもやっぱり RESTful API が好き！と言う方も多いでしょう。僕もそうです。何度痛い目に合っても何故か好き。
まぁそんなことはどうでも良いのですが、OpenSocial RESTful API は中々面白い機能が幾つかあって、
- Partial Update
- Filter & Sort
辺りが挙げられます。Partial Update は冷静に考えると利便性の観点から出来て然るべきなんですが、ここでは触れない事にします。
Filter & Sort の辺りは Open Search 辺りからやってきた概念でしょう。
Filter や Sort なんですけど、例えばこんな風に書きます。
http://example.com/people/@me/@friends?filterBy=displayName&filterOp=startsWith&filterValue=zigo&sortBy=id&sortOrder=descending&count=50&startIndex=1
まぁ特に説明しなくても理解出来るとは思いますけど。
現時点の RESTful API の仕様では filter をもっと複雑に記述するなんて事は出来ません。と言うのも AND なのか OR なのかを指定する仕組みが無いからだと思うのですが、まぁ OR は要らないすよね。
そこで冒頭の JSON-RPC の URL Addressing から Syntax を借りてくると、こんな風に書けるかもしれません。
http://example.com/people/@me/@friends?filterBy(0)=displayName&filterOp(0)=startsWith&filterValue(0)=zigo,kaz,hid&filterBy(1)=gender&filterOp(1)=equals&filterValue(1)=male
この部分をデータ構造にすると、
{ "filterBy": ["displayName", "gender"], "filterOp": ["startsWith", "equals"], "filterValue": [ ["zigo", "kaz", "hid"], "male" ] }
みたいな感じとなり、SQL で表現すれば、
WHERE ( displayName LIKE 'zigo%' OR displayName LIKE 'kaz%' OR displayName LIKE 'hid%' ) AND gender = 'male';
のようになると。
実は某プラットフォームの API v2 ではこの記法が使えるらしいのですが、とりあえず undocument & no supports です。
雑感
とりあえず JSON-RPC に関して仮に GET をサポートするのであれば本家の方の仕様( Base64 )の方がすっきりしていて良いかなと思います。あと、一般論としてクエリパラメータとして何か構造化されたデータを埋め込む場合も、これと同様の手法の方が便利だろうなと思います。
RESTful API と filter の議論ですけど、こういうのもありかなとは思います。
*1:監視用途とかなら意味があるかもしれない
IV, NV などを B モジュールで調べる
makamaka さんが YAPC Asia 2010 にて発表した XSからPPへ - YAPC::Asia Tokyo 2010 に既に書いてあるんだけど、備忘録を兼ねて。
JSON にする際に違いが出てくる訳ですがまずは論より証拠。
$ perl -MJSON -e 'warn encode_json(+{ foo => 1, bar => "1", baz => 0 + "1" })'
{"bar":"1","baz":1,"foo":1} at -e line 1.これらは IV なのか PV なのかばっちり判定してくれる訳ですね。API なんかのユースケースだとこの辺りを厳密にやらねばならないので、この辺りの制御はちゃんとやらないといかんのです。
その前に Devel::Peek で中を見てみると、
$ perl -MDevel::Peek -e 'my $i = "1"; Dump($i);' SV = PV(0x10041040) at 0x10043be0 REFCNT = 1 FLAGS = (PADMY,POK,pPOK) PV = 0x10042020 "1"\0 CUR = 1 LEN = 4 $ perl -MDevel::Peek -e 'my $i = 1; Dump($i);' SV = IV(0x10043be0) at 0x10043be0 REFCNT = 1 FLAGS = (PADMY,IOK,pIOK) IV = 1 $ perl -MDevel::Peek -e 'my $i = "1"; $i = 0 + $i; Dump($i);' SV = PVIV(0x10062010) at 0x10043be0 REFCNT = 1 FLAGS = (PADMY,IOK,pIOK) IV = 1 PV = 0x10042020 "1"\0 CUR = 1 LEN = 4
となり、一度 PV として初期化された変数も IV に変換すると PVIV になると。*1
B モジュールで B::SVp_IOK とか使えるってどこにも書いてない気がするんだけど気のせいだろうか。とりあえず sv.h で定義されている定数のうちその辺りは使えるみたいです。
B モジュールの svref_2object() によって B::SV オブジェクトにしつつ、そのオブジェクトメソッドである FLAGS を用いればどういう flag が立ってるか分かります。
即ちこんな感じでチェック出来ますよと。
#!/usr/bin/perl use strict; use warnings; use B; use Test::More; sub iv_ok { my $sv = shift; return ( B::svref_2object( \$sv )->FLAGS & B::SVp_IOK ) ? 1 : 0; } sub nv_ok { my $sv = shift; return ( B::svref_2object( \$sv )->FLAGS & B::SVp_NOK ) ? 1 : 0; } subtest 'IV' => sub { my $sv1 = 1; is( iv_ok($sv1), 1, 'IV' ); is( nv_ok($sv1), 0, 'not NV' ); my $sv2 = "1"; is( iv_ok($sv2), 0, 'not IV' ); is( nv_ok($sv2), 0, 'not NV' ); $sv2 = 0 + $sv2; is( iv_ok($sv2), 1, 'IV' ); is( nv_ok($sv2), 0, 'not NV' ); done_testing; }; subtest 'NV' => sub { my $sv1 = 1.0; is( iv_ok($sv1), 0, 'not IV' ); is( nv_ok($sv1), 1, 'NV' ); my $sv2 = "1.0"; is( iv_ok($sv2), 0, 'not IV' ); is( nv_ok($sv2), 0, 'not NV' ); $sv2 = 0 + $sv2; is( iv_ok($sv2), 0, 'not IV' ); is( nv_ok($sv2), 1, 'NV' ); done_testing; }; done_testing;
*1:多分この辺りは lestrrat さんの本の8章辺りにきっと書いてあるはず
