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

# Event

JJUG CCC 2019 Spring
2019年05月18日（土）

http://www.java-users.jp/ccc2019spring/#/

# Session

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

http://www.java-users.jp/ccc2019spring/#/sessions/d2e9b342-6473-449e-8ee7-e35ef26bbd85

# Sumally

皆さん、API使っていますか!? 世界のAPI Management 市場は2022年までに現在の2倍(3,000億円)の市場規模になると予想されていて、今後今まで以上にAPI を使ったマッシュアップは重要性を増すようです! でも、一口にAPIと言っても、単純にRESTという切り口だけでは収まらなくなってきました。そんな多様化され、今後ますます増え続けるAPIのマッシュアップを迅速に行うために、知っておいて損は無いJava開発者のためのAPIスタイル・エコシステムの活用方法をお伝えします!

Transcript

1. © 2019 CData Software Japan, LLC | www.cdata.com/jp Java クライント実装におけるAPIスタイル頂上決戦! 野良REST vs GraphQL vs OData vs OpenAPI (Swagger) 2019/05 CData Software Japan JJUG CCC 2019 Spring
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. © 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 を使いやすく」をミッションにクラウドデータ接続を標準化
4. © 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
5. © 2019 CData Software Japan, LLC | www.cdata.com/jp 今日の参考資料とAPIデモ環境はこちらで公開中！ http://bit.ly/CDataJJUG2019S
6. © 2019 CData Software Japan, LLC | www.cdata.com/jp 0. はじめに
7. © 2019 CData Software Japan, LLC | www.cdata.com/jp このセッションの（裏）目的 API を開発する側ではなく API を使う側が もっと楽をできるようになってほしい そのために知っているだけで楽をできる API エコシステムのポイント
8. © 2019 CData Software Japan, LLC | www.cdata.com/jp APIエコシステムってなんだろう？ おそらくそれぞれの立場・立ち位置で定義が変わる
9. © 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 に付与する環境
10. © 2019 CData Software Japan, LLC | www.cdata.com/jp そもそも私達はなぜAPI実装で「苦労」するのか？ 私達はなぜ「楽」がしたいのか？
11. © 2019 CData Software Japan, LLC | www.cdata.com/jp 「REST」がプロトコルでは無いから
12. © 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）
13. © 2019 CData Software Japan, LLC | www.cdata.com/jp Web API を REST たらしめる“原則“（≠規約） • Stateless：ステートレスなクライアント/サーバプロトコル • Uniform Interface：すべての情報（リソース）に適用できるHTTPメソッドの定義 • Addressability：リソースを一意に識別する「汎用的な構文（URL）」の定義 • Connectability：アプリケーションの情報と状態遷移の両方を扱うことができる「ハイ パーメディア（リソースリンク）の使用」 上記の原則に従っているアーキテクチャを REST ful と言ったりするが あくまで “原則“ であり ”規約” ではない！
14. © 2019 CData Software Japan, LLC | www.cdata.com/jp 「REST」によって引き起こされる悲劇
15. © 2019 CData Software Japan, LLC | www.cdata.com/jp こんなAPIは使いづらい API あるある！ APIあるから繋げて使えるでしょ、と言われたけど。。。 実録
16. © 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: <http://qiita.com/api/v2/use rs?page=1>; rel="first", なし ・同じ会社のAPIでも微妙に違う ・ヘッダに記載していたり、ボディに記載していたり
17. © 2019 CData Software Japan, LLC | www.cdata.com/jp 404 のはずなのに 200 でエラーが返ってくる ・成功なのに失敗？ ・リソース名が間違っていたはずなのに、200番 ・原因が不明瞭になるので、サポートの問い合わせが増え る・・・
18. © 2019 CData Software Japan, LLC | www.cdata.com/jp リソース指向と関数指向がまざってる ・リソース指向、関数指向がまざっている 例えばURLが https://XXX.com/getXXX https://XXX.com/findXXX https://XXX.com/users ・詳細検索するときだけ、FindやSearchといったURL
19. © 2019 CData Software Japan, LLC | www.cdata.com/jp リソース名が省略語すぎて、なんのことだかわからない 例えば・・・ ・営業案件 Opportunity がOPP 日本語ローマ字略称は覚えづらく、つらい・・・ ・勘定科目マスタ が KKM とか
20. © 2019 CData Software Japan, LLC | www.cdata.com/jp データを取得したいのにPOST ・例：Bodyで検索条件を指定するから、 POSTメソッドでGETする ・基本的にすべてのエンドポイントがPOST仕 様だったり（統一されているならいいが）
21. © 2019 CData Software Japan, LLC | www.cdata.com/jp 仕様書が PDF・Excel で提供されている！ ・Word ベース や 神エクセル ・ドキュメントと実装の乖離 ・中にはドキュメントがCD-ROMで送られ てくるところも・・・。
22. © 2019 CData Software Japan, LLC | www.cdata.com/jp すべては REST から生まれる 産みの苦しみ REST だからそうなんだけど これを課題と認識することがスタート （※REST API が悪いとは言っていない）
23. © 2019 CData Software Japan, LLC | www.cdata.com/jp なので…
24. © 2019 CData Software Japan, LLC | www.cdata.com/jp なぜ開発者が API エコシステムを 意識する必要があるのか？ ただの Web API や REST と捉えず、 各エコシステムを知っているだけで開発スピードに雲泥の差が出る
25. © 2019 CData Software Japan, LLC | www.cdata.com/jp API エコシステムを知って楽をしよう パブリック API として公開されやすい3種類の API 仕様を取り上げて どれだけ楽ができるかを比較してみる！
26. © 2019 CData Software Japan, LLC | www.cdata.com/jp 1. Swagger（OpenAPI）Code Generate 編
27. © 2019 CData Software Japan, LLC | www.cdata.com/jp Swagger (OpenAPI) って何？ OpenAPI Specification（OAS）は、ソース コードへのアクセス、追加ドキュメント、またはネット ワークトラフィックの検査を必要とせずに、人間とコン ピュータの両方がサービスの機能を発見して理解す ることを可能にする、 プログラミング言語に依存しないREST APIの 標準的なインターフェイス記述を定義します。 引用元： https://github.com/OAI/OpenAPI- Specification
28. © 2019 CData Software Japan, LLC | www.cdata.com/jp Swagger (OpenAPI) って何？
29. © 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 エコシステムで実現している！
30. © 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
31. © 2019 CData Software Japan, LLC | www.cdata.com/jp デモ
32. © 2019 CData Software Japan, LLC | www.cdata.com/jp Swagger を利用するにあたってのポイント ・ドキュメントがひたすらわかりやすい ・認証周りや接続設定はSwagger Specで定義されているパラメータがproperty化さ れていてわかりやすい ・URL パラメータも引数になっているので、迷わない ・JSONのデシリアライズもデシリアライズ用クラスも自動生成
33. © 2019 CData Software Japan, LLC | www.cdata.com/jp 2. OData（Olingo） 編
34. © 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 なプロトコル
35. © 2019 CData Software Japan, LLC | www.cdata.com/jp OData のポイント その1 Query Support URL Components 表形式のデータを参照するための各種URLパラメータを定義しているので カラムのセレクトもフィルタリングもページングも並び替えも迷わない
36. © 2019 CData Software Japan, LLC | www.cdata.com/jp OData のポイント その2 Metadata Endpoint のサポート 使用できるリソース・カラムの構成を取得することができる 取得した内容を元に、HTTPリクエストの構成ができる
37. © 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
38. © 2019 CData Software Japan, LLC | www.cdata.com/jp デモ
39. © 2019 CData Software Japan, LLC | www.cdata.com/jp OData を利用するにあたってのポイント ・ HTTP リクエストを構成するための各メソッドが標準装備。なので、いちいち API のド キュメントを確認する必要が無い 対象のリソースの指定（ordersやorder_details） filterやselectなど、基本的なOData のリクエストパラメータ ページング用のskipやtopなども使えるのでわかりやすい ・メタデータの取得ができるので、動的なデータの取得・出力に対応可能
40. © 2019 CData Software Japan, LLC | www.cdata.com/jp 3. GraphQL 編
41. © 2019 CData Software Japan, LLC | www.cdata.com/jp GraphQL って何？ GraphQL は 2015年 に Facebook が公 開した Web APIのための新しいクエリ言語 独自の構造的なクエリ言語を用いることで、一 つのエンドポイントで複数のリソース、ネストされ た構造体のデータを取得することがしやすいよう に構成されている
42. © 2019 CData Software Japan, LLC | www.cdata.com/jp GraphQL のポイント 例えば REST API ベースでこんな画面を作ろうとしたら
43. © 2019 CData Software Japan, LLC | www.cdata.com/jp GraphQL のポイント RESTの思想で実装する場合、リソースごとのリクエストを都度実施する必要があった
44. © 2019 CData Software Japan, LLC | www.cdata.com/jp GraphQL のポイント GraphQLであれば、一つのリクエストで関係性を持つデータを一括で取得して、 クライアントサイドへレンダリングするということが実現することができる！
45. © 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
46. © 2019 CData Software Japan, LLC | www.cdata.com/jp デモ
47. © 2019 CData Software Japan, LLC | www.cdata.com/jp GraphQL を利用するにあたってのポイント ・ Query を Java のラムダで書くことができて直感的 ・ 1：Nで構成されている Order と OrderDetails の関係性も一度で取得 ・ スキーマ用エンドポイントが提供されているので、JSON デシリアライズも快適 （ただ、ちょっと Java で使うまでの敷居が高い、、、）
48. © 2019 CData Software Japan, LLC | www.cdata.com/jp 4. 比較結果
49. © 2019 CData Software Japan, LLC | www.cdata.com/jp REST GraphQL OData Swagger メタデータ スキーマ ？ サービス次第 ◦ 標準エンドポイントで提供 スキーマチェックも厳しい ◦ 標準エンドポイントで提供 エコシステムも強い △ 取得できるが実際のAPIとの 整合性は保証されない ドキュメント ？ サービス次第 ◦ ドキュメントと一緒に 検証環境も提供 △ ドキュメント生成ツールが 別途必要 ◦ 一番ドキュメントが 使いやすい クライアントSDK ？ サービス次第 △ Java クライアントは 今後に期待？ ◦ エンタープライズ系が 充実している ◦ おそらく対応言語は 一番多く使いやすい 所感 ？ サービス次第 Java Client から使う 敷居は高い 提供サービスは増加 ウォッチする価値はある 一度理解すれば 汎用的に使いやすい エンタープライズ領域に強み Client SDKの 使いやすさはピカイチ 提供サービスが増加の一途
50. © 2019 CData Software Japan, LLC | www.cdata.com/jp でも、別に今回は比較したいわけじゃない
51. © 2019 CData Software Japan, LLC | www.cdata.com/jp なぜ開発者が API のエコシステムを 理解しておくことが大事なのか？ Swagger で CodeGenerate することを知らなければ、 クラス名を一から記述することになり OData で Metadata を取得することを知らなければ、 動的なアプリケーションは作りづらい Web API を ただの REST と捉えてしまうと、 実は大事なものを見落としてしまう 仕様であること、エコシステムがあることを理解しているだけで、 開発者が取れる選択肢は格段に多くなり、開発スピードも上がる！
52. © 2019 CData Software Japan, LLC | www.cdata.com/jp 最後に… これまでの面倒なことを一切気にしたくないあなたに！
53. © 2019 CData Software Japan, LLC | www.cdata.com/jp CData JDBC Driver 誤解を恐れずに言えば、 Web API を SQL で実行できるようにするライブラリ
54. © 2019 CData Software Japan, LLC | www.cdata.com/jp 使い慣れた IDE/AP サーバから 150 を超える Web API・NoSQL に JDBC(SQL) 接続
55. © 2019 CData Software Japan, LLC | www.cdata.com/jp やってくれることは単純 リクエストされた SQL を分解し、Web API の HTTP Request に組み立て レスポンスの JSON をレコードセット形式にしてクライアントに返すという仕組み
56. © 2019 CData Software Japan, LLC | www.cdata.com/jp デモ
57. © 2019 CData Software Japan, LLC | www.cdata.com/jp CData Driver を利用するにあたってのポイント ・ SQLでアクセスできるので、HTTP動詞やWeb APIのエンドポイントURLなどを意識す ることなく、データの取得操作が実施可能 ・JOINやWhereなどもサポートしているので、各エンドポイントからデータを取得して、それ をクライアントサイドでマージするといった処理を書く必要が無い ・スキーマ・メタデータ情報にもアクセスすることができるので、動的な値の取得が可能
58. © 2019 CData Software Japan, LLC | www.cdata.com/jp 是非、各仕様・エコシステムを理解してもらいながら 開発に役立ててください！ （CData Driver も使ってみてね！）
59. © 2019 CData Software Japan, LLC | www.cdata.com/jp CData ブースで大喜利企画やってます！ #JJUG私のSQL でツイート中