狠狠撸

狠狠撸Share a Scribd company logo

JSON Based Web Services

?Download as KEY, PDF?
?
Toru Yamaguchi
Toru Yamaguchi
1 of 39
JSON based Web Service Toru Yamaguchi <zigorou@cpan.org>
JSON Pointer
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) JSON Document JSON Pointer { "foo": ["bar", "baz"], "": 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) JSON Document JSON Pointer { "foo": ["bar", "baz"], "": 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) JSON Document JSON Pointer { "foo": ["bar", "baz"], "": 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) JSON Document JSON Pointer { "foo": ["bar", "baz"], "": 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) JSON Document JSON Pointer { "foo": ["bar", "baz"], "": 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) JSON Document JSON Pointer { "foo": ["bar", "baz"], "": 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) JSON Document JSON Pointer { "foo": ["bar", "baz"], "": 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
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 JSON Patch Document ? JSON Pointer で指定され た target を削除する { "op": "remove", "path": "/a/b/c" ? path は存在する物でな ければならない }
Operation - replace JSON Patch Document ? JSON Pointer で指定され た 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 JSON Patch Document ? JSON Pointer で指定され た path を to で指定され { た場所に複製する "op": "copy", "path": "/a/b/c", "to": "/a/b/d" ? to が配列の要素を指定 している場合に幾つか } 制約がある
Operation - test JSON Patch Document ? JSON Pointer で指定され た 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
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 のような使い方も出来る
Conclusion
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 のように 結果に対して適切なリンクを貼る事も可能
Thanks ? Any question?

More Related Content

JSON Based Web Services

  • 1. JSON based Web Service Toru Yamaguchi <zigorou@cpan.org>
  • 3. JSON Pointer とは ? XML で言う所の XPath に相当するもの ? Spec ? http://tools.ietf.org/html/draft-ietf- appsawg-json-pointer-04
  • 4. JSON Pointer の ABNF json-pointer = *( "/" reference-token ) reference-token = *( unescaped / escaped ) unescaped = %x00-2E / %x30-7D / %x7F-10FFFF escaped = "~" ( "0" / "1" )
  • 5. 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"]
  • 6. 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 }
  • 7. Example (2) JSON Document JSON Pointer { "foo": ["bar", "baz"], "": 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 }
  • 8. Example (3) JSON Document JSON Pointer { "foo": ["bar", "baz"], "": 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 }
  • 9. Example (4) JSON Document JSON Pointer { "foo": ["bar", "baz"], "": 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 }
  • 10. Example (5) JSON Document JSON Pointer { "foo": ["bar", "baz"], "": 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 }
  • 11. Example (5) JSON Document JSON Pointer { "foo": ["bar", "baz"], "": 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 }
  • 12. Example (6) JSON Document JSON Pointer { "foo": ["bar", "baz"], "": 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 }
  • 13. Example (5) JSON Document JSON Pointer { "foo": ["bar", "baz"], "": 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 }
  • 14. Usage of JSON Pointer ? 任意の要素を指し示す事が出来る ? WAF 等でも primitive なデータの探索、取 得に使える (c.f. Mojolicious) ? URI Fragment Identi?er Representation (Section 6) ? JSON Document 中の任意の要素を表す URI を提供出来る (とても大事)
  • 16. 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 にちょっと似ている
  • 17. 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" } ]
  • 18. JSON Patch document ? 全体としては配列 ? 配列の各要素に operation を表す object が入る ? 各 operation object には op, path というフィールドがある ? op はオペレーション名 ? path は適用対象を示す JSON Pointer ? 各 operation object には引数のような key-value が指定さ れる (value, to)
  • 19. Operation の適用 ? operation object 配列の各要素を先頭か ら順番に適用していきます ? 途中で error が発生した場合は処理が終 了します
  • 20. Operation - add JSON Patch Document ? JSON Pointer で指定され た path に value で指定 { された値を追加する "op": "add", "path": "/a/b/c", "value": ["foo", "bar"] ? path は root か存在する object または array でな } ければならない
  • 21. Operation - remove JSON Patch Document ? JSON Pointer で指定され た target を削除する { "op": "remove", "path": "/a/b/c" ? path は存在する物でな ければならない }
  • 22. Operation - replace JSON Patch Document ? JSON Pointer で指定され た target の値を value で { 指定された物と置き換 "op": "replace", える "path": "/a/b/c", "value": 42 } ? path は存在する物でな ければならない
  • 23. Operation - move JSON Patch Document ? JSON Pointer で指定された path を to で指定された場所 { に移動する "op": "move", "path": "/a/b/c", ? path の内容を remove "to": "/a/b/d" ? remove された物を add } ? to が配列の要素を指定して いる場合に幾つか制約があ る
  • 24. Operation - copy JSON Patch Document ? JSON Pointer で指定され た path を to で指定され { た場所に複製する "op": "copy", "path": "/a/b/c", "to": "/a/b/d" ? to が配列の要素を指定 している場合に幾つか } 制約がある
  • 25. Operation - test JSON Patch Document ? JSON Pointer で指定され た path の値が value で { 指定された物と一致す "op": "test", るか確認する "path": "/a/b/c", "value": "foo" } ? 一致しない場合は後 続の operation が実行 されず、即座にエラー になる
  • 26. Usage of JSON Patch ? Media Type が "application/json-patch" と なっているので RESTful API で PATCH メソッドと共に差分適用を表現する ? See RFC 5789 ? JSON 相当で記述された設定のプリプロ セッサなど
  • 28. JSON Schema とは ? http://json-schema.org/ ? http://tools.ietf.org/html/draft-zyp-json-schema-03 ? 暫く動きが見えないけど現在 draft-04 策定 中です ? JSON Document に対して Validation, Documentation, Hyperlink を与える為のスキー マ記述形式のこと
  • 29. Validation & Documentation ? だいぶ syntax が多いので詳細は割愛し ます:( ? 詳しくは Spec 見て下さい ? 基本的には primitive な値に対して制約 をつける事が出来ます
  • 30. 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 } } }
  • 31. Explain for the schema ? Authorization Code Grant の Authorization Request の クエリパラメータについての Schema になっています ? title, description で documentation が可能です ? type で型を指定し、型ごとに指定可能な制約やデ フォルト値等が指定出来ます ? また type は JSON Pointer を使って任意の JSON Schema の任意の要素の定義を参照する事が出来ます
  • 32. Hyperlinks ? JSON Document に Hyperlink を与える為 の JSON Schema の拡張 ? 具体的には Schema に対する relation, endpoint, http method, encoding type, request property 等を指定出来る
  • 33. 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": {} } } ] }
  • 34. Explain to the hyper schema ? https://gist.github.com/3838576 に完全版を書いてみまし た ? Authorization Response を Resource として、この Resource を作成する為の Hyperlink を定義しました。 ? method, enctype, properties で request format も定義 出来る ? rel で指定可能な物は大体記述可能なので Service Descriptor のような使い方も出来る
  • 36. JSON Pointer ? シンプルなのでデータ取得方法として様々 な所で利用用途がある ? JSON Patch で利用されている ? また JSON Document の内部リンクとして も利用価値がある ? JSON Schema で利用されている
  • 37. JSON Patch ? RESTful API で PUT メソッドを利用した Partial Update (要は差分適用) の代わり に PATCH メソッド + JSON Patch が使 える ? ex) OpenSocial Appdata API
  • 38. JSON Schema ? Validation として様々な言語から再利用可能 ? Documentation はツールが整備されれば将来性あり ? http://sk-api-browser.heroku.com/ などの事例もある ? Hyperlink まで利用すると API の記述言語としても使 える ? 応用すれば Facebook Graph API Explorer のように 結果に対して適切なリンクを貼る事も可能

Editor's Notes

  1. \n
  2. \n
  3. \n
  4. \n
  5. \n
  6. \n
  7. \n
  8. \n
  9. \n
  10. \n
  11. \n
  12. \n
  13. \n
  14. \n
  15. \n
  16. \n
  17. \n
  18. \n
  19. \n
  20. \n
  21. \n
  22. \n
  23. \n
  24. \n
  25. \n
  26. \n
  27. \n
  28. \n
  29. \n
  30. \n
  31. \n
  32. \n
  33. \n
  34. \n
  35. \n
  36. \n
  37. \n
  38. \n
  39. \n