Java クライント実装におけるAPIスタイル頂上決戦! 野良REST vs GraphQL vs OData vs OpenAPI (Swagger)
5 likes4,703 views
Burikaigi 2019 の発表資料です。 https://toyama-eng.connpass.com/event/111062/ #### Blog & Github Java クライント開発における Web API の実装アプローチ その1 Web API を活用する上で意識したい APIエコシステム http://bit.ly/2MmT1Py その2 一般的なREST API編 http://bit.ly/2Bdt40D https://github.com/sugimomoto/CData.WebAPI.JavaConsole.StandardRequest その3 Swagger（OpenAPI）Code Generate 編 http://bit.ly/2RNLZJF https://github.com/sugimomoto/CData.WebAPI.JavaConsole.SwaggerBaseRequest その4 OData 編 http://bit.ly/2S3x3pV https://github.com/sugimomoto/CData.WebAPI.JavaConsole.ODataRequest その5 GraphQL 編 http://bit.ly/2RaKhNb https://github.com/sugimomoto/CData.WebAPI.JavaConsole.GraphQLRequest その6 CData Driver編 http://bit.ly/2Mte1nE https://github.com/sugimomoto/CData.WebAPI.JavaConsole.CDataDriverRequest その7 まとめ REST vs GraphQL vs Swagger vs OData http://bit.ly/2B3d0OF
Java クライント実装におけるAPIスタイル頂上決戦! 野良REST vs GraphQL vs OData vs OpenAPI (Swagger)
- 1. © 2018 CData Software Japan, LLC | www.cdata.com/jp Java クライント実装におけるAPIスタイル頂上決戦! 野良REST vs GraphQL vs OData vs OpenAPI (Swagger) 2019/01 CData Software Japan Burikaigi 2019
- 2. See the World as a Database Speaker 杉本 和也：Kazuya Sugimoto • CData Software Japan, LLC Lead Engineer • Microsoft MVP for Business Solution(Dynamics CRM/365) Blog：Morning Girl http://kageura.hatenadiary.jp/ Twitter：@sugimomoto Facebook：sugimomoto
- 3. © 2018 CData Software Japan, LLC | www.cdata.com/jp About CData Software Bi-directional Access to Live App, Database, & Web API Data Through Standard Drivers ・CData Software, Inc. / Started: 1994 (/nsoftware) ・Location: Chapel Hill, NC a spin-off of /n software ・CData Japan: 2016/6 (JV with Infoteria) ・20年以上にわたりデータ関連コンポーネントを提供 ・100+ 対応データソース ・「API を使いやすく」をミッションにクラウドデータ接続を標準化
- 4. © 2018 CData Software Japan, LLC | www.cdata.com/jp 1. はじめに
- 5. © 2018 CData Software Japan, LLC | www.cdata.com/jp 世界のAPI Management 市場は2022年までに 現在の2倍（3,000億円）の市場規模 API Management Market Augmenting Rapidly To Reach USD 3,436.16 Million by 2022 https://www.zionmarketresearch.com/news/api-management-market
- 6. © 2018 CData Software Japan, LLC | www.cdata.com/jp ますます重要性を増す「APIエコシステム」 APIを利用したエコシステムの構築を阻む壁は何か？ https://codezine.jp/article/detail/10938
- 7. © 2018 CData Software Japan, LLC | www.cdata.com/jp 最近よく取り上げられる 「API エコシステム」は 提供者側を中心としたトピック API は使うユーザー・開発者が居て、 はじめて真価を発揮するもの じゃあ、API エコシステムって開発者には 関係無いトピックなの？
- 8. © 2018 CData Software Japan, LLC | www.cdata.com/jp そんなことは無い！
- 9. © 2018 CData Software Japan, LLC | www.cdata.com/jp なぜ開発者が API エコシステムを 意識する必要があるのか？ ただのWeb APIやRESTと捉えず、 各エコシステムを知っているだけで開発スピードに雲泥の差が出る
- 10. © 2018 CData Software Japan, LLC | www.cdata.com/jp 本日のお話 「Java クライアント実装にとっての API エコシステム」 REST vs OData vs Swagger vs GraphQL
- 11. © 2018 CData Software Japan, LLC | www.cdata.com/jp Swagger HubAzure Web AppHeroku 今回のセッションでは検証環境を用意しています！ CData API Sever OData HASURA GraphQL PostgreSQL Swagger Spec CodeGen etc User サンプルデータはすべて同じ PostgreSQL DB
- 12. © 2018 CData Software Japan, LLC | www.cdata.com/jp 今日の資料とAPIデモ環境はこちらで公開中！ http://bit.ly/CDataBurikaigi2019 （イベント限定公開）
- 13. © 2018 CData Software Japan, LLC | www.cdata.com/jp 2. 野良 REST 編
- 14. © 2018 CData Software Japan, LLC | www.cdata.com/jp 改めて REST ってなんだっけ？ REST = Representational State Transfer ＞Representational State Transfer (REST) は、ウェブのような分散ハイ パーメディアシステムのためのソフトウェアアーキテクチャのスタイルのひとつである。 引用元：Wikipedia REST（https://ja.wikipedia.org/wiki/REST）
- 15. © 2018 CData Software Japan, LLC | www.cdata.com/jp Web API を REST たらしめる“原則“（≠規約） • Stateless：ステートレスなクライアント/サーバプロトコル • Uniform Interface：すべての情報（リソース）に適用できるHTTPメソッドの定義 • Addressability：リソースを一意に識別する「汎用的な構文（URL）」の定義 • Connectability：アプリケーションの情報と状態遷移の両方を扱うことができる「ハイ パーメディア（リソースリンク）の使用」 上記の原則に従っているアーキテクチャを REST ful と言ったりするが あくまで “原則“ であり ”規約” ではない！
- 16. © 2018 CData Software Japan, LLC | www.cdata.com/jp デモ
- 17. © 2018 CData Software Japan, LLC | www.cdata.com/jp REST API を利用するにあたってのポイント・課題 ・取得した JSON のデシリアライズ先のクラス定義が面倒 ・リクエストパラメータで何を実行すればいいのかドキュメント頼み ページングどうするの？ フィルターはどうかけられるの？ ・APIを取得した後のロジックよりも、取得するためのロジック・コードが多く必要 ・API へのアップデート対応には無策 REST だからそうなんだけど これを課題と認識することがスタート
- 18. © 2018 CData Software Japan, LLC | www.cdata.com/jp 3. Swagger（OpenAPI）Code Generate 編
- 19. © 2018 CData Software Japan, LLC | www.cdata.com/jp Swagger (OpenAPI) って何？ OpenAPI Specification（OAS）は、ソースコードへ のアクセス、追加ドキュメント、またはネットワークトラフィッ クの検査を必要とせずに、人間とコンピュータの両方が サービスの機能を発見して理解することを可能にする、 プログラミング言語に依存しないREST APIの標準的 なインターフェイス記述を定義します。 引用元：https://github.com/OAI/OpenAPI- Specification
- 20. © 2018 CData Software Japan, LLC | www.cdata.com/jp Swagger (OpenAPI) って何？
- 21. © 2018 CData Software Japan, LLC | www.cdata.com/jp Swagger (OpenAPI) のポイント Tool Description Swagger Spec REST APIに対して Swaggerの仕様に準じたドキュメント Swagger Core REST APIの実装からSwagger specを生成するためのライ ブラリ Swagger Codegen コマンドラインツール Swagger JSONからクライアントコード生 成 Swagger UI SWagger 準拠 API （Swagger SPec）から動的にドキュ メントを生成するツール Swagger Editor ブラウザ上で動くJSON/YAMLのエディタリアルタイムで構文 チェック 引用元：Swaggerとは何か？ プログラマでありたい http://blog.takuros.net/entry/2015/12/02/082248 ドキュメントの生成から、クライアントサイド・サーバーサイドの Code Generate まで Swagger エコシステムで実現している！
- 22. © 2018 CData Software Japan, LLC | www.cdata.com/jp Swagger (OpenAPI) で公開しているAPI SendGrid https://github.com/sendgrid/s endgrid-oai CloudSign https://app.swaggerhub.com/a pis/CloudSign/cloudsign- web_api/0.8.0 SmartHR https://developer.smarthr.jp/ap i/index.html
- 23. © 2018 CData Software Japan, LLC | www.cdata.com/jp デモ
- 24. © 2018 CData Software Japan, LLC | www.cdata.com/jp Swagger を利用するにあたってのポイント ・ドキュメントがひたすらわかりやすい ・認証周りや接続設定はSwagger Specで定義されているパラメータがproperty化さ れていてわかりやすい ・URL パラメータも引数になっているので、迷わない ・JSONのデシリアライズもデシリアライズ用クラスも自動生成
- 25. © 2018 CData Software Japan, LLC | www.cdata.com/jp 4. OData（Olingo） 編
- 26. © 2018 CData Software Japan, LLC | www.cdata.com/jp OData って何？ ODataは、データモデルの記述、およびそれらのモデルに従ったデータの編集および照会を サポートするプロトコル。 ・ メタデータ：特定のデータプロバイダによって公開されるデータモデルの機械可読の記述。 ・ データ：データエンティティのセットとそれらの間の関係。 ・ クエリー：サービスがフィルタリングとデータへの変換を実行するよう要求し、結果を返す。 ・ 編集：データの作成、更新、および削除。 ・ 操作：カスタムロジックの呼び出し ・ ボキャブラリ：カスタムセマンティクスの付加 引用元：http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1- protocol.html 表形式データの“編集”および“照会”を効率化・定義した REST ful なプロトコル
- 27. © 2018 CData Software Japan, LLC | www.cdata.com/jp OData のポイント その1 Query Support URL Components 表形式のデータを参照するための各種URLパラメータを定義しているので カラムのセレクトもフィルタリングもページングも並び替えも迷わない
- 28. © 2018 CData Software Japan, LLC | www.cdata.com/jp OData のポイント Metadata Endpoint のサポート 使用できるリソース・カラムの構成を取得することができる 取得した内容を元に、HTTPリクエストの構成ができる
- 29. © 2018 CData Software Japan, LLC | www.cdata.com/jp OData で公開されている API Dynamics 365 https://dynamics.microsoft.co m/ja-jp/ Salesforce https://www.salesforce.com/jp/ SAP HANA https://www.sap.com/japan/pr oducts/hana.html
- 30. © 2018 CData Software Japan, LLC | www.cdata.com/jp デモ
- 31. © 2018 CData Software Japan, LLC | www.cdata.com/jp OData を利用するにあたってのポイント ・ HTTP リクエストを構成するための各メソッドが標準装備。なので、いちいち API のド キュメントを確認する必要が無い 対象のリソースの指定（ordersやorder_details） filterやselectなど、基本的なOData のリクエストパラメータ ページング用のskipやtopなども使えるのでわかりやすい ・メタデータの取得ができるので、動的なデータの取得・出力に対応可能
- 32. © 2018 CData Software Japan, LLC | www.cdata.com/jp 5. GraphQL 編
- 33. © 2018 CData Software Japan, LLC | www.cdata.com/jp GraphQL って何？ GraphQL は 2015年 に Facebook が公 開した Web APIのための新しいクエリ言語 独自の構造的なクエリ言語を用いることで、一 つのエンドポイントで複数のリソース、ネストされ た構造体のデータを取得することがしやすいよう に構成されている
- 34. © 2018 CData Software Japan, LLC | www.cdata.com/jp GraphQL のポイント 例えば REST API ベースでこんな画面を作ろうとしたら
- 35. © 2018 CData Software Japan, LLC | www.cdata.com/jp GraphQL のポイント RESTの思想で実装する場合、リソースごとのリクエストを都度実施する必要があった
- 36. © 2018 CData Software Japan, LLC | www.cdata.com/jp GraphQL のポイント GraphQLであれば、一つのリクエストで関係性を持つデータを一括で取得して、 クライアントサイドへレンダリングするということが実現することができる！
- 37. © 2018 CData Software Japan, LLC | www.cdata.com/jp GraphQL で公開されている API Github https://developer.github.com/v 4/ shopify https://help.shopify.com/en/ap i/custom- storefronts/storefront- api/graphql SWAPI GraphQL Wrapper https://github.com/graphql/sw api-graphql
- 38. © 2018 CData Software Japan, LLC | www.cdata.com/jp デモ
- 39. © 2018 CData Software Japan, LLC | www.cdata.com/jp GraphQL を利用するにあたってのポイント ・ Query を Java のラムダで書くことができて直感的 ・ 1：Nで構成されている Order と OrderDetails の関係性も一度で取得 ・ スキーマ用エンドポイントが提供されているので、JSON デシリアライズも快適 （ただ、ちょっと Java で使うまでの敷居が高い、、、）
- 40. © 2018 CData Software Japan, LLC | www.cdata.com/jp 6. 番外編 CData JDBC Driver
- 41. © 2018 CData Software Japan, LLC | www.cdata.com/jp CData JDBC Drivers って何？
- 42. © 2018 CData Software Japan, LLC | www.cdata.com/jp 使い慣れた IDE/AP サーバから 100 を超える クラウドサービス・NoSQL に JDBC(SQL) 接続
- 43. © 2018 CData Software Japan, LLC | www.cdata.com/jp 使い慣れた IDE/AP サーバから 100 を超える クラウドサービス・NoSQL に JDBC(SQL) 接続 リクエストされた SQL を分解し、Web API の HTTP Request に組み立て レスポンスの JSON をレコードセット形式にしてクライアントに返すという仕組み
- 44. © 2018 CData Software Japan, LLC | www.cdata.com/jp デモ
- 45. © 2018 CData Software Japan, LLC | www.cdata.com/jp CData Driver を利用するにあたってのポイント ・ SQLでアクセスできるので、HTTP動詞やWeb APIのエンドポイントURLなどを意識す ることなく、データの取得操作が実施可能 ・JOINやWhereなどもサポートしているので、各エンドポイントからデータを取得して、それ をクライアントサイドでマージするといった処理を書く必要が無い ・スキーマ・メタデータ情報にもアクセスすることができるので、動的な値の取得が可能
- 46. © 2018 CData Software Japan, LLC | www.cdata.com/jp 7. まとめ
- 47. © 2018 CData Software Japan, LLC | www.cdata.com/jp REST・Swagger・OData・GraphQL 比較表 REST GraphQL OData Swagger メタデータ スキーマ ？ サービス次第 ○ 標準エンドポイントで提供 スキーマチェックも厳しい ○ 標準エンドポイントで提供 エコシステムも強い △ 取得できるが実際のAPIとの 整合性は保証されない ドキュメント ？ サービス次第 ○ ドキュメントと一緒に 検証環境も提供 △ ドキュメント生成ツールが 別途必要 ○ 一番ドキュメントが 使いやすい クライアントSDK ？ サービス次第 △ Java クライアントは 今後に期待 ○ エンタープライズ系が 充実している ○ おそらく対応言語は 一番多く使いやすい
- 48. © 2018 CData Software Japan, LLC | www.cdata.com/jp Swagger・OData・GraphQL 使ってみた所感 ［Swagger］ ・Code Generate で生成した Client SDKの使いやすさはピカイチ ・ただ、ドキュメントのアップデートに気を使っているかどうかは、そのプロバイダーにかかっている ・現在も使用しているプロバイダーは増えているので、覚えておいて損はない ［OData］ ・スキーマやリクエストのコントロールのアプローチは確立されている ・アーキテクチャとしての複雑さ、使う敷居の高さは若干否めない ・Salesforce・Dynamics 365・SAP などが OData なのでエンタープライズ領域としては強みがある ［GraphQL］ ・Java Client から使う、となるとまだまだ敷居の高さは否めない ・React といった Java Script系クライアント利用がまだ多い ・でも、Github や Shopify がパブリックなAPIを公開、Microsoft も一部ベータ的に GraphQL API を公開し始め たので、今後ウォッチしておく価値はある
- 49. © 2018 CData Software Japan, LLC | www.cdata.com/jp 最後に。なぜ開発者が API のエコシステムを 理解しておくことが大事なのか？ Swagger で CodeGenerate することを知らなければ、 クラス名を一から記述することになり OData で Metadata を取得することを知らなければ、 動的なアプリケーションは作りづらい Web API を ただの REST と捉えてしまうと、 実は大事なものを見落としてしまう 仕様であること、エコシステムがあることを理解しているだけで、 開発者が取れる選択肢は格段に多くなり、開発スピードも上がる！
- 50. © 2018 CData Software Japan, LLC | www.cdata.com/jp 是非、各仕様・エコシステムを理解してもらいながら 開発に役立ててください！ （CData Driver も使ってみてね！）
- 51. © 2018 CData Software Japan, LLC | www.cdata.com/jp CData Software Japan では メンバーを募集中！ https://www.wantedly.com/projects/265684
- 52. © 2018 CData Software Japan, LLC | www.cdata.com/jp Thanks!