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

Recomendados

Recomendados

Mais conteúdo relacionado

Destaque

Destaque (15)

Semelhante a JSON Based Web Services

Semelhante a JSON Based Web Services (20)

Mais de Toru Yamaguchi

Mais de Toru Yamaguchi (20)

Último

Último (9)

JSON Based Web Services

Notas do Editor