似たような傾向があるAPIをグルーピングして「スタイル」とここでは呼ばせていただくことにします。

「API」というと「RESTかな?」と思う方も多いのではないかと思いますが、そもそも最初にはやったのはSOAPだったり、また現在GraphQLやイベントドリブンのAPIが人気が高まっていたりなどして、意外とバリエーションがあり、かつ使い分けが進んでいるのが現在の状況です。

現在はまだ悩んだらREST！で大丈夫なのですが、それぞれメリットデメリットがあり、どこでそのAPIを使うのかで使い分けされていることがありますので、特徴はおさえておきたいと思います。

特に海外のAPIクライアント開発者に訴求したい場合、日本よりさらに使い分けが進んでいますので、本当にRESTで良いのかは一度考えていただいた方が良いと思います。

RPCスタイル (SOAP, gRPCなど)

RPC = リモートプロシージャーコール。

APIというと最初にはやったのはSOAPで、10年くらい前は「Webサービス」と呼んでいたと思います。おそらくこの「Webサービス」という呼び名はW3Cがマシン間のインタラクションをサポートするソフトウェアシステムのことを「Webサービス」と呼んでいたので、そこから来た名前ではないでしょうか。

SOAPとgRPCの共通の特徴としては、

• インターフェース定義ファイルがあること (.wsdl, .proto)

• クライアントとサーバーとの両方にインターフェース定義ファイルをインポートしてProxyをたて、データのシリアライズ/デシリアライズをすることで、通信しやすいデータ形式と、コードの中で扱いやすいデータ形式を両立していること

特にgRPCはHTTP/2で使うことになりますので、さらにスピードアップします。gRPCとRESTの速度のベンチマークは検索すると出てくるのですが、例えばこの辺。

メリット

通信速度です！

デメリット

インターフェース定義ファイルをクライアント側とサーバー側で維持しないといけないことです。
その性質上、度々バージョンアップされるようなAPIや、誰の手に渡るかわからないようなひろく配布するアプリケーションでは使いにくいです。

インターフェース定義ファイルにインターフェースが定義されているということは、いかなる更新であってもインターフェース定義ファイルを交換しないといけないからです。
したがって更新した時に確実にインターフェース定義ファイルの差し替えを管理できる範囲で使用します。例えばシステム間連携にしか使わないことがわかっているようなAPIなどです。

データサービス (REST, GraphQLなど)

データオブジェクトのやり取りを中心にしたスタイルをデータサービススタイルと呼ぼうと思います。我々のよく知るRESTとGraphQLをここに分類しました。

どちらも例えば「Users」のようなデータオブジェクトに対してCreate/Read/Update/Deleteなどのデータベースのオペレーションを想起させるような指示を組み合わせ、オブジェクトに対して何をしたいのかをAPIクライアント側から指示することによりサーバー側に処理をさせるためのものです。

RESTとGraphQLとの違いはこちらを参照してください。

GraphQL触ったことないよ！という方はぜひ触ってみてください。仕組みがわかると非常に使いやすいです。SOAPやRESTを使いながら「直接SQL文叩かせろ！」と感じたことがあるのは私だけではないはずです。

メリット

なんといってもわかりやすい！
RESTはHTTPがわかれば基本が分かります。GraphQLはSQLに近い使い勝手を提供するものです。HTTPやSQLがわかれば使い方がなんとなくわかることがメリット。

したがってシステムの外側に対して公開されるAPIに使用されます。

デメリット

データサービススタイルのAPIは大きな弱点はありません。ここではRESTとGraphQLそれぞれのデメリットとさせてください。

RESTの弱点は上記の記事で書いた通り、

• 粒度が悩ましいこと (常に固定の属性群を返す仕組みであるため)

GraphQLの弱点は

• まだまだ馴染みがないインターフェースであること

• ツール群が充実していないこと

• スペルチェックのように、特定のデータベーステーブルのやりとりではない単純な機能を実装する目的では使えないこと

• アクセスコントロールは全てコードの中で記述せざるを得ないこと (API Gatewayを使ってURLごとにアクセスコントロールを仕掛けるやり方ができないこと)

GraphQLの弱点の多くはおそらく時が経つにつれてカバーされ、ベストプラクティスが整備されていくのではと推測しています。

ハイパーメディア (Roy FieldingのREST)

データサービスのところに我々のよく知るRESTを入れ、ここにはRoy FieldingのRESTを入れました。
この2つは厳密には別物です。

さまざまな議論は置いておいて、ここでは我々のよく知るRESTとRoy FieldingのRESTを見分けることができることは重要だということはハイライトさせていただきます。
なぜなら本やブログ記事などさまざまな媒体で気軽に「REST」と書かれているものが、どちらを指しているかをきちんと説明していません。お勉強する際に我々のよく知るRESTとRoy FieldingのRESTが見分けられないと、全く別のスタイルのAPIの話が知識の中で混在し、混乱してしまうからです。

どう違うかと見分け方はこちらの記事に書きましたのでご参照ください。

実際に触ってみたい方はこちらを手がかりにしてはいかがでしょうか。

メリット

• HTML言語のようにマークアップルールを設計することがメイン。マークアップルールが変更されなければ、HTML言語とブラウザのように何が起こっても壊れないアプリケーションができる。

デメリット

• 実装例が少ない

• 設計のオーバーヘッド。マークアップルールを設計するのは大変難しい。

• 扱えるAPI側の開発者、APIクライアントの開発者が少ない

イベントドリブン (IoT, Pub/Subなど)

IoTの人気とともに広まってきたといえるAPIです。
今までの3つのスタイルはHTTPの上でやり取りされることが多いものでした。
このイベントドリブンスタイルはHTTP以外でやり取りされることが多いですが、HTTPを使うこともあります。

イベントドリブンスタイルのAPIについても過去に記事を書いていました。

「イベントドリブン」と名前がついたのが比較的最近の話だっただけで、この通信モデルそのものは古くから使い込まれています。

例えば監視のソリューションはこのモデルでできていることが多いです。

監視のエージェントは監視対象のサーバーにインストールされ、特定の事象が発生するかどうかモニターしています。例えば「CPU利用率80％」のような通知すべき事象が設定されているわけです。
いざCPU利用率80％が検知されたら、エージェントは監視のサーバーに起こった事象を報告します。「AサーバーがCPU利用率80％になりました」。

イベントドリブンのAPIは「AサーバーがCPU利用率80％になりました」のように、通知すべき事象を検知した時に、APIサーバーに対して報告をするためのインテグレーションのインターフェースです。

イベントドリブンのAPIは特にIoTからのデータの受信やマイクロサービスアーキテクチャでのサービス間のやり取りに使用されます。
またバッチの置き換えにはイベントドリブンをベースとしたマイクロサービス (イベントドリブンアーキテクチャ) などが使われます。

メリット

軽量でAPIサーバーとAPIクライアントをより一層疎結合にすることができます。
レイテンシーの問題になりにくいこともメリットです。レスポンスはAck (受信通知) レベルのレスポンスになりますので、迅速に返答されます。

デメリット

非同期の通信かつ検知した事象の報告型 (イベント型) であるため、APIクライアントが例えば画面を描画する、あるいは処理をするためのインプットが欲しい時の通信には向かないことです。