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

© 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

View Slide

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

View Slide

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 を使いやすく」をミッションにクラウドデータ接続を標準化

View Slide

Swagger Hub
Azure Web App
Heroku
今回のセッションでは検証環境を用意しています！
CData API Sever
OData
HASURA
GraphQL
PostgreSQL Swagger Spec
CodeGen etc
User
サンプルデータはすべて同じ
PostgreSQL DB

View Slide

今日の参考資料とAPIデモ環境はこちらで公開中！
http://bit.ly/CDataJJUG2019S

View Slide

0. はじめに

View Slide

このセッションの（裏）目的
API を開発する側ではなく
API を使う側が
もっと楽をできるようになってほしい
そのために知っているだけで楽をできる
API エコシステムのポイント

View Slide

APIエコシステムってなんだろう？
おそらくそれぞれの立場・立ち位置で定義が変わる

View Slide

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 に付与する環境

View Slide

そもそも私達はなぜAPI実装で「苦労」するのか？
私達はなぜ「楽」がしたいのか？

View Slide

「REST」がプロトコルでは無いから

View Slide

改めて REST ってなんだっけ？
REST = Representational State Transfer
＞Representational State Transfer (REST) は、ウェブのような分散ハイ
パーメディアシステムのためのソフトウェアアーキテクチャのスタイルのひとつである。
引用元：Wikipedia REST（https://ja.wikipedia.org/wiki/REST）

View Slide

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

View Slide

「REST」によって引き起こされる悲劇

View Slide

こんなAPIは使いづらい
API あるある！
APIあるから繋げて使えるでしょ、と言われたけど。。。
実録

View Slide

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

View Slide

404 のはずなのに 200 でエラーが返ってくる
・成功なのに失敗？
・リソース名が間違っていたはずなのに、200番
・原因が不明瞭になるので、サポートの問い合わせが増え
る・・・

View Slide

リソース指向と関数指向がまざってる
・リソース指向、関数指向がまざっている
例えばURLが
https://XXX.com/getXXX
https://XXX.com/findXXX
https://XXX.com/users
・詳細検索するときだけ、FindやSearchといったURL

View Slide

リソース名が省略語すぎて、なんのことだかわからない
例えば・・・
・営業案件 Opportunity がOPP
日本語ローマ字略称は覚えづらく、つらい・・・
・勘定科目マスタが KKM とか

View Slide

データを取得したいのにPOST
・例：Bodyで検索条件を指定するから、
POSTメソッドでGETする
・基本的にすべてのエンドポイントがPOST仕
様だったり（統一されているならいいが）

View Slide

仕様書が PDF・Excel で提供されている！
・Word ベースや神エクセル
・ドキュメントと実装の乖離
・中にはドキュメントがCD-ROMで送られ
てくるところも・・・。

View Slide

すべては REST から生まれる
産みの苦しみ
REST だからそうなんだけど
これを課題と認識することがスタート
（※REST API が悪いとは言っていない）

View Slide

なので…

View Slide

なぜ開発者が API エコシステムを
意識する必要があるのか？
ただの Web API や REST と捉えず、
各エコシステムを知っているだけで開発スピードに雲泥の差が出る

View Slide

API エコシステムを知って楽をしよう
パブリック API として公開されやすい3種類の API 仕様を取り上げて
どれだけ楽ができるかを比較してみる！

View Slide

1. Swagger（OpenAPI）Code Generate 編

View Slide

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

View Slide

Swagger (OpenAPI) って何？

View Slide

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

View Slide

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

View Slide

デモ

View Slide

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

View Slide

2. OData（Olingo）編

View Slide

OData って何？
ODataは、データモデルの記述、およびそれらのモデルに従ったデータの編集および照会を
サポートするプロトコル。
・メタデータ：特定のデータプロバイダによって公開されるデータモデルの機械可読の記述。
・データ：データエンティティのセットとそれらの間の関係。
・クエリー：サービスがフィルタリングとデータへの変換を実行するよう要求し、結果を返す。
・編集：データの作成、更新、および削除。
・操作：カスタムロジックの呼び出し
・ボキャブラリ：カスタムセマンティクスの付加
引用元：http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-
protocol.html
表形式データの“編集”および“照会”を効率化・定義した
REST ful なプロトコル

View Slide

OData のポイントその1
Query Support URL Components
表形式のデータを参照するための各種URLパラメータを定義しているので
カラムのセレクトもフィルタリングもページングも並び替えも迷わない

View Slide

OData のポイントその2
Metadata Endpoint のサポート
使用できるリソース・カラムの構成を取得することができる
取得した内容を元に、HTTPリクエストの構成ができる

View Slide

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

View Slide

デモ

View Slide

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

View Slide

3. GraphQL 編

View Slide

GraphQL って何？
GraphQL は 2015年に Facebook が公
開した Web APIのための新しいクエリ言語
独自の構造的なクエリ言語を用いることで、一
つのエンドポイントで複数のリソース、ネストされ
た構造体のデータを取得することがしやすいよう
に構成されている

View Slide

GraphQL のポイント
例えば REST API ベースでこんな画面を作ろうとしたら

View Slide

RESTの思想で実装する場合、リソースごとのリクエストを都度実施する必要があった

View Slide

GraphQLであれば、一つのリクエストで関係性を持つデータを一括で取得して、
クライアントサイドへレンダリングするということが実現することができる！

View Slide

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

View Slide

デモ

View Slide

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

View Slide

4. 比較結果

View Slide

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

View Slide

でも、別に今回は比較したいわけじゃない

View Slide

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

View Slide

最後に…
これまでの面倒なことを一切気にしたくないあなたに！

View Slide

CData JDBC Driver
誤解を恐れずに言えば、
Web API を SQL で実行できるようにするライブラリ

View Slide

使い慣れた IDE/AP サーバから 150 を超える
Web API・NoSQL に JDBC(SQL) 接続

View Slide

やってくれることは単純
リクエストされた SQL を分解し、Web API の HTTP Request に組み立て
レスポンスの JSON をレコードセット形式にしてクライアントに返すという仕組み

View Slide

デモ

View Slide

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

View Slide

是非、各仕様・エコシステムを理解してもらいながら
開発に役立ててください！
（CData Driver も使ってみてね！）

View Slide

CData ブースで大喜利企画やってます！
#JJUG私のSQL
でツイート中

View Slide

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

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

Kazuya Sugimoto

More Decks by Kazuya Sugimoto

Other Decks in Technology

Featured

Transcript