Java クライント実装におけるAPIスタイル頂上決戦! 野良REST vs GraphQL vs OData vs OpenAPI (Swagger)

Slide 1

Slide 1 text

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

© 2019 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年以上にわたりデータ関連コンポーネントを提供・150+ 対応データソース・「API を使いやすく」をミッションにクラウドデータ接続を標準化

Slide 4

Slide 4 text

© 2019 CData Software Japan, LLC | www.cdata.com/jp Swagger Hub Azure Web App Heroku 今回のセッションでは検証環境を用意しています！ CData API Sever OData HASURA GraphQL PostgreSQL Swagger Spec CodeGen etc User サンプルデータはすべて同じ PostgreSQL DB

Slide 5

Slide 5 text

Slide 6

Slide 6 text

Slide 7

Slide 7 text

Slide 8

Slide 8 text

Slide 9

Slide 9 text

© 2019 CData Software Japan, LLC | www.cdata.com/jp Web API External Service 3rd Party Tool SDK Protocol Style ここでは、利用者から見る API エコシステム REST・SOAP OData・GraphQL gRPC etc... 各言語ごと Java・C#・PHP Python etc... ETL/BI Tool 帳票・アプリビルダー etc... IFTTT MS Flow etc... Web API の周辺に存在し Developer Experience に付与する環境

Slide 10

Slide 10 text

Slide 11

Slide 11 text

Slide 12

Slide 12 text

© 2019 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）

Slide 13

Slide 13 text

© 2019 CData Software Japan, LLC | www.cdata.com/jp Web API を REST たらしめる“原則“（≠規約） • Stateless：ステートレスなクライアント/サーバプロトコル • Uniform Interface：すべての情報（リソース）に適用できるHTTPメソッドの定義 • Addressability：リソースを一意に識別する「汎用的な構文（URL）」の定義 • Connectability：アプリケーションの情報と状態遷移の両方を扱うことができる「ハイパーメディア（リソースリンク）の使用」上記の原則に従っているアーキテクチャを REST ful と言ったりするがあくまで “原則“ であり ”規約” ではない！

Slide 14

Slide 14 text

Slide 15

Slide 15 text

Slide 16

Slide 16 text

© 2019 CData Software Japan, LLC | www.cdata.com/jp ページングの指定方法が違いすぎる Qiita MoneyForward ページ指定方法 URLパラメータで指定 Page=1 URLパラメータで指定 Page=1 ページ数最大値表示レスポンスヘッダに記載 Total-Count: 6 レスポンスボディに記載 total_count : 6 1ページあたりの表示件数表記 URLパラメータで指定 per_page=20 URLパラメータで指定 Limit=100 次ページリンクレスポンスボディに記載 Link: ; rel="first", なし・同じ会社のAPIでも微妙に違う・ヘッダに記載していたり、ボディに記載していたり

Slide 17

Slide 17 text

Slide 18

Slide 18 text

Slide 19

Slide 19 text

Slide 20

Slide 20 text

Slide 21

Slide 21 text

Slide 22

Slide 22 text

Slide 23

Slide 23 text

Slide 24

Slide 24 text

Slide 25

Slide 25 text

Slide 26

Slide 26 text

Slide 27

Slide 27 text

© 2019 CData Software Japan, LLC | www.cdata.com/jp Swagger (OpenAPI) って何？ OpenAPI Specification（OAS）は、ソースコードへのアクセス、追加ドキュメント、またはネットワークトラフィックの検査を必要とせずに、人間とコンピュータの両方がサービスの機能を発見して理解することを可能にする、プログラミング言語に依存しないREST APIの標準的なインターフェイス記述を定義します。引用元： https://github.com/OAI/OpenAPI- Specification

Slide 28

Slide 28 text

Slide 29

Slide 29 text

© 2019 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 エコシステムで実現している！

Slide 30

Slide 30 text

© 2019 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

Slide 31

Slide 31 text

Slide 32

Slide 32 text

© 2019 CData Software Japan, LLC | www.cdata.com/jp Swagger を利用するにあたってのポイント・ドキュメントがひたすらわかりやすい・認証周りや接続設定はSwagger Specで定義されているパラメータがproperty化されていてわかりやすい・URL パラメータも引数になっているので、迷わない・JSONのデシリアライズもデシリアライズ用クラスも自動生成

Slide 33

Slide 33 text

Slide 34

Slide 34 text

© 2019 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 なプロトコル

Slide 35

Slide 35 text

Slide 36

Slide 36 text

Slide 37

Slide 37 text

© 2019 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

Slide 38

Slide 38 text

Slide 39

Slide 39 text

© 2019 CData Software Japan, LLC | www.cdata.com/jp OData を利用するにあたってのポイント・ HTTP リクエストを構成するための各メソッドが標準装備。なので、いちいち API のドキュメントを確認する必要が無い対象のリソースの指定（ordersやorder_details） filterやselectなど、基本的なOData のリクエストパラメータページング用のskipやtopなども使えるのでわかりやすい・メタデータの取得ができるので、動的なデータの取得・出力に対応可能

Slide 40

Slide 40 text

Slide 41

Slide 41 text

Slide 42

Slide 42 text

Slide 43

Slide 43 text

Slide 44

Slide 44 text

Slide 45

Slide 45 text

© 2019 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

Slide 46

Slide 46 text

Slide 47

Slide 47 text

© 2019 CData Software Japan, LLC | www.cdata.com/jp GraphQL を利用するにあたってのポイント・ Query を Java のラムダで書くことができて直感的・ 1：Nで構成されている Order と OrderDetails の関係性も一度で取得・スキーマ用エンドポイントが提供されているので、JSON デシリアライズも快適（ただ、ちょっと Java で使うまでの敷居が高い、、、）

Slide 48

Slide 48 text

Slide 49

Slide 49 text

© 2019 CData Software Japan, LLC | www.cdata.com/jp REST GraphQL OData Swagger メタデータスキーマ？サービス次第 ○ 標準エンドポイントで提供スキーマチェックも厳しい ○ 標準エンドポイントで提供エコシステムも強い △ 取得できるが実際のAPIとの整合性は保証されないドキュメント？サービス次第 ○ ドキュメントと一緒に検証環境も提供 △ ドキュメント生成ツールが別途必要 ○ 一番ドキュメントが使いやすいクライアントSDK ？サービス次第 △ Java クライアントは今後に期待？ ○ エンタープライズ系が充実している ○ おそらく対応言語は一番多く使いやすい所感？サービス次第 Java Client から使う敷居は高い提供サービスは増加ウォッチする価値はある一度理解すれば汎用的に使いやすいエンタープライズ領域に強み Client SDKの使いやすさはピカイチ提供サービスが増加の一途

Slide 50

Slide 50 text

Slide 51

Slide 51 text

© 2019 CData Software Japan, LLC | www.cdata.com/jp なぜ開発者が API のエコシステムを理解しておくことが大事なのか？ Swagger で CodeGenerate することを知らなければ、クラス名を一から記述することになり OData で Metadata を取得することを知らなければ、動的なアプリケーションは作りづらい Web API をただの REST と捉えてしまうと、実は大事なものを見落としてしまう仕様であること、エコシステムがあることを理解しているだけで、開発者が取れる選択肢は格段に多くなり、開発スピードも上がる！

Slide 52

Slide 52 text

Slide 53

Slide 53 text

Slide 54

Slide 54 text

Slide 55

Slide 55 text

Slide 56

Slide 56 text

Slide 57

Slide 57 text

© 2019 CData Software Japan, LLC | www.cdata.com/jp CData Driver を利用するにあたってのポイント・ SQLでアクセスできるので、HTTP動詞やWeb APIのエンドポイントURLなどを意識することなく、データの取得操作が実施可能・JOINやWhereなどもサポートしているので、各エンドポイントからデータを取得して、それをクライアントサイドでマージするといった処理を書く必要が無い・スキーマ・メタデータ情報にもアクセスすることができるので、動的な値の取得が可能

Slide 58

Slide 58 text

Slide 59

Slide 59 text