API server/client development using JSON Schema #kanrk06

関西Ruby会議06 講演資料

Transcript

1. API server/client development using JSON Schema Masayuki IZUMI - @izumin5210 関西 Ruby 会議 06
2. Ƅ Rekimoto Lab. at the University of Tokyo (2008-2015: Akashi-NCT) Ɠ Enginner at Wantedly, Inc. (2014.9-2015.2: Dmetlabel, Inc.) 2
3. Kobe.rb Asakusa.rb https://www.flickr.com/photos/suzumenonamida/8213183210/ https://www.flickr.com/photos/takkanm/3978417669/
4. We are hiring ! https://www.wantedly.com/companies/wantedly/projects
5. pry(main)> izumin.skill_ratio Ruby JavaScript Android Design
7. 「JSON Schema ?」 ときどき見かけるけど，何がうれしいの？
8. Q: What does it do? JSON Schema ってなにすんの？ A: It describes your JSON data format[1] . JSON のフォーマット記述するやつやで． [1] http://json-schema.org/ 8 API sever/client development using JSON Schema - 関西 Ruby 会議 06
9. What is JSON Schema ? 9 API sever/client development using JSON Schema - 関西 Ruby 会議 06 * Defines structure of JSON data - JSON Schema Core * Provides structual validation - JSON Schema Validation * Defines hyper{text,media} related things - JSON Hyper Schema
10. title: User properties: email: description: email address type: string name: description: user name type: string { "email": "syaro@example.com", "name": "Syaro Kirima" } e.g. JSON Schema Core 10 API sever/client development using JSON Schema - 関西 Ruby 会議 06
11. title: User properties: email: description: email address type: string name: description: user name type: string { "email": "syaro@example.com", "name": "Syaro Kirima" } e.g. JSON Schema Core 11 API sever/client development using JSON Schema - 関西 Ruby 会議 06
12. title: User properties: email: description: email address type: string name: description: user name type: string { "email": "syaro@example.com", "name": "Syaro Kirima" } e.g. JSON Schema Core 12 API sever/client development using JSON Schema - 関西 Ruby 会議 06 7 primitive types: array, boolean, integer, number, null, object, string
13. title: User properties: email: description: email address type: string format: email name: description: user name type: string maxLength: 32 required: - email - name { "email": "syaro@example.com", "name": "Syaro Kirima" } e.g. JSON Schema Validation 13 API sever/client development using JSON Schema - 関西 Ruby 会議 06
14. title: User properties: email: description: email address type: string format: email name: description: user name type: string maxLength: 32 required: - email - name { "email": "syaro@example.com", "name": "Syaro Kirima" } e.g. JSON Schema Validation 14 API sever/client development using JSON Schema - 関西 Ruby 会議 06
15. title: User properties: email: description: email address type: string format: email name: description: user name type: string maxLength: 32 required: - email - name { "email": "syaro@example.com", "name": "Syaro Kirima" } e.g. JSON Schema Validation 15 API sever/client development using JSON Schema - 関西 Ruby 会議 06 Defined validation keywords: maximum, maxLength, pattern, maxItems, enum, allOf, anyOf, definitions, ...
16. title: User links: - href: "/api/users" method: GET rel: instances title: List properties: # define some properties [ { "email": "cocoa@example.com", "name": "Cocoa Hoto" }, { "email": "syaro@example.com", "name": "Syaro Kirima" } ] e.g. JSON Hyper-Schema 16 API sever/client development using JSON Schema - 関西 Ruby 会議 06
17. title: User links: - href: "/api/users" method: GET rel: instances title: List properties: # define some properties [ { "email": "cocoa@example.com", "name": "Cocoa Hoto" }, { "email": "syaro@example.com", "name": "Syaro Kirima" } ] e.g. JSON Hyper-Schema 17 API sever/client development using JSON Schema - 関西 Ruby 会議 06 response body from `GET /api/users`
18. title: User links: - href: "/api/users" method: POST rel: craete schema: properties: name: "$ref": "#/properties/name" title: Create properties: # define some properties e.g. JSON Hyper-Schema 18 API sever/client development using JSON Schema - 関西 Ruby 会議 06
19. title: User links: - href: "/api/users" method: POST rel: craete schema: properties: name: "$ref": "#/properties/name" title: Create properties: # define some properties e.g. JSON Hyper-Schema 19 API sever/client development using JSON Schema - 関西 Ruby 会議 06 JSON Schema(subschema) for request parameter
20. title: User links: - href: "/api/users" method: POST rel: craete schema: properties: name: "$ref": "#/properties/name" title: Create properties: # define some properties e.g. JSON Hyper-Schema 20 API sever/client development using JSON Schema - 関西 Ruby 会議 06 "$ref": "#/foo/bar" JSON Reference[2] #/foo/bar JSON Pointer[3] [2] http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03 [3] http://tools.ietf.org/html/rfc6901
21. title: User links: - href: "/api/users/{(%23%2Fproperties%2Fname)}" method: GET rel: instance title: self properties: # define some properties e.g. JSON Hyper-Schema 21 API sever/client development using JSON Schema - 関西 Ruby 会議 06
22. title: User links: - href: "/api/users/{(%23%2Fproperties%2Fname)}" method: GET rel: instance title: self properties: # define some properties e.g. JSON Hyper-Schema 22 API sever/client development using JSON Schema - 関西 Ruby 会議 06 "/foo/bar/{(%23baz)}" URI Template[4] [4] http://tools.ietf.org/html/rfc6570
23. 「何がうれしいの ?」 JSON データのフォーマット定義出来るだけ？ API のドキュメントにもなるよー的な？
24. できること その① Validate request parameters 24 API sever/client development using JSON Schema - 関西 Ruby 会議 06 client server POST /api/posts { "body": " 大阪なう ", "user_id": 1 } user_idｲﾗﾈ
25. できること その② Validate API response body 25 API sever/client development using JSON Schema - 関西 Ruby 会議 06 client server POST /api/posts { "body": " 大阪なう " } レスポンスの形式間違ってるから 500
26. できること その③ Generate API client 26 API sever/client development using JSON Schema - 関西 Ruby 会議 06 JSON Schema json js rb java d.ts API client Generate !
27. できること その④ Generate API document 27 API sever/client development using JSON Schema - 関西 Ruby 会議 06 JSON Schema json API document Generate !
28. What can JSON Schema do ? 28 API sever/client development using JSON Schema - 関西 Ruby 会議 06 * Validates request parameter - rack-json_schema が便利 * Validates response body - rack-json_schema が便利 * Generates API client - いろんな言語，環境に存在 * Generates API document - prmd, jdoc がいい感じ
29. What can JSON Schema do ? 29 API sever/client development using JSON Schema - 関西 Ruby 会議 06 * Validates request parameter * Validates response body * Generates API client * Generates API document \ Strong Parameter でいいじゃん / \ テスト書いてたらいらないじゃん / \ API の変更あったらどうすんの /
32. 「ホントにうれしいポイント」 値の validation ？ クライアントやドキュメントの生成？ JSON Schema による Web API 設計の最大の利点はそこじゃない！
33. 33 API sever/client development using JSON Schema - 関西 Ruby 会議 06 突然ですが… Ruby のイケてるところ といえば？
34. 34 API sever/client development using JSON Schema - 関西 Ruby 会議 06 突然ですが… Ruby のイケてるところ といえば？ テストの書きやすさ ですよね？ [ 要出典 ]
35. JSON Schema の 一番イケてる使い方 テスト支援ツールとしての JSON Schema 35 API sever/client development using JSON Schema - 関西 Ruby 会議 06 client server JSON Schema json response validation mock API
36. JSON Schema の 一番イケてる使い方 テスト支援ツールとしての JSON Schema 36 API sever/client development using JSON Schema - 関西 Ruby 会議 06 client server JSON Schema json response validation mock API
37. JSON Schema の 一番イケてる使い方 テスト支援ツールとしての JSON Schema 37 API sever/client development using JSON Schema - 関西 Ruby 会議 06 client server JSON Schema json response validation mock API
38. JSON Schema の 一番イケてる使い方 テスト支援ツールとしての JSON Schema 38 API sever/client development using JSON Schema - 関西 Ruby 会議 06 client server JSON Schema (fixed) json response validation mock API
39. JSON Schema の 一番イケてる使い方 テスト支援ツールとしての JSON Schema 39 API sever/client development using JSON Schema - 関西 Ruby 会議 06 client server JSON Schema (fixed) json response validation mock API
40. JSON Schema の 一番イケてる使い方 テスト支援ツールとしての JSON Schema 40 API sever/client development using JSON Schema - 関西 Ruby 会議 06 client server (fixed) JSON Schema (fixed) json response validation mock API
41. JSON Schema の 一番イケてる使い方 テスト支援ツールとしての JSON Schema 41 API sever/client development using JSON Schema - 関西 Ruby 会議 06 client (fixed) server (fixed) JSON Schema (fixed) json response validation mock API
42. Server/Client どちらも JSON Schema を テストに利用する（validation/mock） 仕様変更があればテストが落ちるから 対応漏れがなくなる（CI しよう） 仕様変更は JSON Schema から 42 API sever/client development using JSON Schema - 関西 Ruby 会議 06
43. その他 JSON Schema じょうほう 43 API sever/client development using JSON Schema - 関西 Ruby 会議 06 * Ruby 界隈は JSON Schema がわりと盛ん - Heroku さん Increments さんありがとうございます - おもしろ gem やイイ感じの知見が多い
44. その他 JSON Schema じょうほう 44 API sever/client development using JSON Schema - 関西 Ruby 会議 06 * JS 界隈は… - JSON（JavaScript Object Notation）とは何だったのか - 自分で node module 作るハメになった - json-schema-parser / json-schema-mockifier - 僕の屍を越えて行ってください
45. 「JSON 手書きつらい…」 なんなんだこの大量の {} と "" は… ド M かよ…
46. Write JSON Schema in YAML 46 API sever/client development using JSON Schema - 関西 Ruby 会議 06 # -y: yaml として出力 $ prmd init -y User > doc/schemata/user.yml $ prmd init -y Post > doc/schemata/post.yml # 1 つの .json に結合 $ prmd combine --meta doc/meta.yml -o doc/schema.json doc/schemata interagent/prmd
48. Write JSON Schema in DSL 48 API sever/client development using JSON Schema - 関西 Ruby 会議 06 r7kamura/json_world Ruby の DSL で Schema が定義できる type に JsonWorld なクラスを渡せる （$ref からの脱却！！）
49. 「Conclusion」 JSON Schema たのしい！（ぐるぐる目
50. Why JSON Schema ? 50 API sever/client development using JSON Schema - 関西 Ruby 会議 06 KEYWORDS = [ "microservices", "mobile first", "SPA" ]
51. Why JSON Schema ? 51 API sever/client development using JSON Schema - 関西 Ruby 会議 06 API
52. Why JSON Schema ? 52 API sever/client development using JSON Schema - 関西 Ruby 会議 06 API Mock json JSON Schema
53. Why JSON Schema ? 53 API sever/client development using JSON Schema - 関西 Ruby 会議 06 API Mock json JSON Schema
56. Conclusion - Why JSON Schema ? 54 API sever/client development using JSON Schema - 関西 Ruby 会議 06 JSON Schema の価値 - API をモック化することでボトルネックにならない - ちゃんとテスト回せば変更にも強い - クライアント側もちゃんとテスト書こう！ - 実装に JSON Schema という " 制約 " をつける
57. https://www.wantedly.com/companies/wantedly/projects