JSON Based Web Services

JSON based
Web Service
Toru Yamaguchi <zigorou@cpan.org>

JSON Pointer とは

• XML で言う所の XPath に相当するもの
• Spec
• http://tools.ietf.org/html/draft-ietf-
appsawg-json-pointer-04

JSON Pointer の ABNF

json-pointer = *( "/" reference-token )
reference-token = *( unescaped / escaped )
unescaped = %x00-2E / %x30-7D / %x7F-10FFFF
escaped = "~" ( "0" / "1" )

JSON Pointer と Object
Access
JSON Pointer Object Access
obj
/ obj[""]
/foo obj["foo"]
/0 obj[0]
/foo/2 obj["foo"][2]
/0/bar obj[0]["bar"]

Example (1)
JSON Document JSON Pointer
{
"foo": ["bar", "baz"],
"": 0,
"a/b": 1,
"c%d": 2,
"e^f": 3,
"g|h": 4,
"ij": 5,
"k"l": 6,
" ": 7,
"m~n": 8
}

Example (2)
{
"": 0,
"a/b": 1, // the whole document
"c%d": 2, json_pointer(doc, "")
"e^f": 3,
"g|h": 4,
"ij": 5,
"k"l": 6,
" ": 7,
"m~n": 8
}

Example (3)
{
"": 0,
"a/b": 1, json_pointer(doc, "/foo")
"c%d": 2,
"e^f": 3,
"g|h": 4,
"ij": 5,
"k"l": 6,
" ": 7,
"m~n": 8
}

Example (4)
{
"": 0,
"a/b": 1, json_pointer(doc, "/foo/0")
"c%d": 2,
"e^f": 3,
"g|h": 4,
"ij": 5,
"k"l": 6,
" ": 7,
"m~n": 8
}

Example (5)
{
"": 0,
"a/b": 1, json_pointer(doc, "/")
"c%d": 2,
"e^f": 3,
"g|h": 4,
"ij": 5,
"k"l": 6,
" ": 7,
"m~n": 8
}

Example (5)
{
"": 0,
"a/b": 1, // escaped "/" as "~1"
"c%d": 2, json_pointer(doc, "/a~1b")
"e^f": 3,
"g|h": 4,
"ij": 5,
"k"l": 6,
" ": 7,
"m~n": 8
}

Example (6)
{
"": 0,
"a/b": 1, // slash and one space
"c%d": 2, json_pointer(doc, "/ ")
"e^f": 3,
"g|h": 4,
"ij": 5,
"k"l": 6,
" ": 7,
"m~n": 8
}

Example (5)
{
"": 0,
"a/b": 1, // escaped "~" as "~0"
"c%d": 2, json_pointer(doc, "/m~0n")
"e^f": 3,
"g|h": 4,
"ij": 5,
"k"l": 6,
" ": 7,
"m~n": 8
}

Usage of JSON Pointer
• 任意の要素を指し示す事が出来る

• WAF 等でも primitive なデータの探索、取
得に使える (c.f. Mojolicious)

• URI Fragment Identiﬁer Representation (Section
6)
• JSON Document 中の任意の要素を表す
URI を提供出来る (とても大事)

JSON Patch とは
• Text の差分に対する diff/patch

• JSON の差分に対する JSON Patch

• http://tools.ietf.org/html/draft-ietf-appsawg-json-
patch-05
• 差分を表現する JSON Patch document

• 差分を適用する operation

• MongoDB の operator にちょっと似ている

JSON Patch Example
[
{ "op": "test", "path": "/a/b/c", "value": "foo" },
{ "op": "remove", "path": "/a/b/c" },
{ "op": "add", "path": "/a/b/c",
"value": [ "foo", "bar" ] },
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "path": "/a/b/c", "to": "/a/b/d" },
{ "op": "copy", "path": "/a/b/c", "to": "/a/b/e" }
]

JSON Patch document
• 全体としては配列

• 配列の各要素に operation を表す object が入る

• 各 operation object には op, path というフィールドがある

• op はオペレーション名

• path は適用対象を示す JSON Pointer

• 各 operation object には引数のような key-value が指定さ
れる (value, to)

Operation の適用

• operation object 配列の各要素を先頭か
ら順番に適用していきます

• 途中で error が発生した場合は処理が終
了します

Operation - add
JSON Patch Document • JSON Pointer で指定され
た path に value で指定
{
された値を追加する
"op": "add",
"path": "/a/b/c",
"value": ["foo", "bar"] • path は root か存在する
object または array でな
}
ければならない

Operation - remove
た target を削除する
{
"op": "remove",
"path": "/a/b/c"
• path は存在する物でな
}

Operation - replace
た target の値を value で
{
指定された物と置き換
"op": "replace",
える
"path": "/a/b/c",
"value": 42
} • path は存在する物でな

Operation - move
JSON Patch Document • JSON Pointer で指定された
path を to で指定された場所
{ に移動する
"op": "move",
"path": "/a/b/c", • path の内容を remove

"to": "/a/b/d"
• remove された物を add
}
• to が配列の要素を指定して
いる場合に幾つか制約があ
る

Operation - copy
た path を to で指定され
{
た場所に複製する
"op": "copy",
"path": "/a/b/c",
"to": "/a/b/d" • to が配列の要素を指定
している場合に幾つか
}
制約がある

Operation - test
た path の値が value で
{
指定された物と一致す
"op": "test",
るか確認する
"path": "/a/b/c",
"value": "foo"
} • 一致しない場合は後
続の operation が実行
されず、即座にエラー
になる

Usage of JSON Patch
• Media Type が "application/json-patch" と
なっているので RESTful API で PATCH
メソッドと共に差分適用を表現する

• See RFC 5789
• JSON 相当で記述された設定のプリプロ
セッサなど

JSON Schema とは
• http://json-schema.org/
• http://tools.ietf.org/html/draft-zyp-json-schema-03
• 暫く動きが見えないけど現在 draft-04 策定
中です

• JSON Document に対して Validation,
Documentation, Hyperlink を与える為のスキー
マ記述形式のこと

Validation &
Documentation
• だいぶ syntax が多いので詳細は割愛し
ます:(

• 詳しくは Spec 見て下さい
• 基本的には primitive な値に対して制約
をつける事が出来ます

Schema for OAuth 2.0 -
Authorization Code Grant
{
"id": "http://schema.example.com/oauth/2.0/authorization_request",
"title": "OAuth 2.0 Authorization Code Grant Response Object",
"properties": {
"code": {
"title": "The authorization code",
"type": "string",
"required": true
},
"state": {
"title": "An opaque value",
"type": "string",
"required": false
}
}
}

Explain for the schema
• Authorization Code Grant の Authorization Request の
クエリパラメータについての Schema になっています

• title, description で documentation が可能です

• type で型を指定し、型ごとに指定可能な制約やデ
フォルト値等が指定出来ます

• また type は JSON Pointer を使って任意の JSON
Schema の任意の要素の定義を参照する事が出来ます

Hyperlinks

• JSON Document に Hyperlink を与える為
の JSON Schema の拡張

• 具体的には Schema に対する relation,
endpoint, http method, encoding type,
request property 等を指定出来る

Extending Schema for OAuth
2.0 Authorization Code Grant
{
"id": "http://schema.example.com/oauth/2.0/authorization_request",
"title": "OAuth 2.0 Authorization Code Grant Response Object",
"properties": { },
"links": [
{
"title": "Authorization endpoint",
"href": "http://connect.example.com/authorize",
"rel": "create",
"enctype": "application/x-www-form-urlencoded"
"properties": {
"response_type": {}, "client_id": {},
"redirect_uri": {}, "scope": {}, "state": {}
}
}
]
}

Explain to the hyper
schema
• https://gist.github.com/3838576 に完全版を書いてみまし
た

• Authorization Response を Resource として、この
Resource を作成する為の Hyperlink を定義しました。

• method, enctype, properties で request format も定義
出来る

• rel で指定可能な物は大体記述可能なので Service
Descriptor のような使い方も出来る

JSON Pointer
• シンプルなのでデータ取得方法として様々
な所で利用用途がある

• JSON Patch で利用されている

• また JSON Document の内部リンクとして
も利用価値がある

• JSON Schema で利用されている

JSON Patch

• RESTful API で PUT メソッドを利用した
Partial Update (要は差分適用) の代わり
に PATCH メソッド + JSON Patch が使
える

• ex) OpenSocial Appdata API

JSON Schema
• Validation として様々な言語から再利用可能

• Documentation はツールが整備されれば将来性あり

• http://sk-api-browser.heroku.com/ などの事例もある

• Hyperlink まで利用すると API の記述言語としても使
える

• 応用すれば Facebook Graph API Explorer のように
結果に対して適切なリンクを貼る事も可能

JSON Based Web Services

More Related Content

Viewers also liked

Similar to JSON Based Web Services

More from Toru Yamaguchi

JSON Based Web Services

Editor's Notes