システム設計チートシート: API スタイル - REST、GraphQL、WebSocket、Webhook、RPC/gRPC、SOAP

これは、システム アーキテクチャ設計における特定のトピックの要点を簡単に説明する一連の記事の続きです。最初の記事は 読めます ここから API アーキテクチャとは、ソフトウェア コンポーネントがどのように対話するかを決定する一連のルール、プロトコル、およびツールを指します。 API のアーキテクチャは、通信を容易にするだけではありません。また、この通信が効率的、安全、スケーラブルであることを保証することも重要です。 適切に設計された API アーキテクチャはシステムのパフォーマンスを大幅に向上させることができますが、設計が不十分な API アーキテクチャはボトルネック、セキュリティの脆弱性、メンテナンスの悪夢につながる可能性があります。 さまざまなスタイルの API アーキテクチャ 最も一般的な API 設計スタイルは次のとおりです。 (Representational State Transfer) は、標準メソッドと HTTP プロトコルを使用する最もよく使用されるスタイルです。これは、ステートレス性、クライアント/サーバー アーキテクチャ、キャッシュ可能性などの原則に基づいています。フロントエンド クライアントとバックエンド サービスの間でよく使用されます。 REST は API 用のクエリ言語です。リソースごとにエンドポイントの固定セットを公開する REST とは異なり、GraphQL ではクライアントが必要なデータを正確にリクエストできるため、オーバーフェッチが削減されます。 GraphQL は、TCP 経由の双方向通信を可能にするプロトコルです。クライアントは Web ソケットを使用して、バックエンド システムからリアルタイムの更新を取得します。 WebSocket 、あるシステムが別のシステムに特定のイベントについてリアルタイムで通知できるようにするメカニズムです。これはユーザー定義の HTTP コールバックです。 Webhook は 、あるサービスがネットワーク内の別のコンピューターにあるサービスからプロシージャ/メソッドを要求するために使用できるプロトコルです。通常、低遅延、高速通信向けに設計されています。 RPC (gRPC) は Web サービスを実装するために構造化された情報を交換するためのプロトコルです。 XML に依存しており、堅牢性とセキュリティ機能で知られていますが、現在はレガシー プロトコルと考えられています。 SOAP は、 各プロトコルの長所、短所、使用例を個別に見てみましょう。 休む は、標準的な規則とプロトコルを使用するアーキテクチャ スタイルであり、理解しやすく、実装しやすくなっています。ステートレスな性質と標準 HTTP メソッドの使用により、Web ベースの API を構築するための一般的な選択肢となっています。 REST REST は長い間 API を構築するための事実上の標準でしたが、GraphQL のような他のスタイルも登場し、データのクエリと操作のためのさまざまなパラダイムを提供しています。 : XML、JSON、HTML、プレーンテキスト 形式 : HTTP/HTTPS トランスポートプロトコル 主要な概念と特徴 : REST では、すべてがリソースです。リソースは、タイプ、関連データ、他のリソースとの関係、およびリソース上で動作する一連のメソッドを持つオブジェクトです。リソースは、その URI (通常は URL) によって識別されます。 リソース : REST サービスは多くの場合、リソースに対する CRUD (作成、読み取り、更新、削除) 操作に直接マップされます。 CRUD 操作 : REST システムは標準の HTTP メソッドを使用します。 HTTP メソッド GET: リソースを取得します。 POST: 新しいリソースを作成します。 PUT/PATCH: 既存のリソースを更新します。 DELETE: リソースを削除します。 : REST API は、標準の HTTP ステータス コードを使用して、API リクエストの成功または失敗を示します。 ステータス コード 2xx - 承認と成功 200 - OK 201 - 作成されました 202 - 承認されました 3xx - リダイレクト 301 - 永久に移動されました 302 - 見つかりました 303 - その他を見る 4xx - クライアント エラー 400不正な要求 401 - 不正 403禁止します 404お探しのページが見つかりませんでした 405 - メソッドは許可されていません 5xx - サーバーエラー 500内部サーバーエラー 501 - 未実装 502不正なゲートウェイ 503 - サービスが利用できません 504ゲートウェイのタイムアウト : クライアントからサーバーへの各リクエストには、リクエストを理解して処理するために必要なすべての情報が含まれている必要があります。サーバーは、リクエスト間のクライアントの状態について何も保存しないでください。 ステートレス : REST はクライアントサーバーモデルに基づいています。クライアントはユーザー インターフェイスとエクスペリエンスを担当し、サーバーはリクエストの処理、ビジネス ロジックの処理、およびデータの保存を担当します。 クライアントサーバー : サーバーからの応答をクライアントがキャッシュできます。サーバーは、応答がキャッシュ可能かどうかを示す必要があります。 キャッシュ可能 : 通常、クライアントは、エンド サーバーに直接接続されているのか、仲介サーバーに接続されているのかを知ることができません。中間サーバーは、負荷分散を有効にし、共有キャッシュを提供することにより、システムのスケーラビリティを向上させることができます。 階層化システム アプリケーションのエンジンとしてのハイパーメディア Stat は、サーバーが応答で動的に提供するハイパーメディアに完全に基づいてクライアントが Web アプリケーションと対話し、ナビゲートできるようにする REST Web サービスの原則であり、疎結合と検出可能性を促進します。 HATEOAS: 使用例 : 多くの Web サービスは REST API 経由で機能を公開しており、サードパーティの開発者がサービスを統合および拡張できるようにしています。 Web サービス : モバイル アプリケーションは、多くの場合、REST API を使用してバックエンド サーバーと通信し、データを取得および送信します。 モバイル アプリケーション : SPA は REST API を使用して、ページ全体を更新することなくコンテンツを動的に読み込みます。 シングル ページ アプリケーション (SPA) 組織内のシステムは、REST API を使用して通信し、データを共有できます。 システム間の統合: 例 リクエスト 「/user/42」を取得 応答 { "id": 42, "name": "Alex", "links": { "role": "/user/42/role" } } グラフQL 、特に複雑なシステムやフロントエンドに高い柔軟性が必要な場合に、API を構築するためのより柔軟で堅牢かつ効率的なアプローチを提供します。これにより、責任の一部がサーバーからクライアントに移され、クライアントがデータ要件を指定できるようになります。 GraphQL は すべてのシナリオで REST に代わるわけではありませんが、特にアプリケーションのネットワーク化と分散化が進むにつれて、多くの状況で魅力的な代替手段となります。 : JSON 形式 : HTTP/HTTPS トランスポートプロトコル 主要な概念と特徴 : クライアントが必要なデータをリクエストできるようになり、必要なすべての情報を 1 回のリクエストで取得できるようになります。 API のクエリ言語 : GraphQL API は、エンドポイントではなく、タイプとフィールドの観点から編成されています。強力な型システムを使用して API の機能を定義します。 API で公開されるすべての型は、GraphQL スキーマ定義言語 (SDL) を使用してスキーマに書き込まれます。 タイプ システム : さまざまなリソースに複数のエンドポイントがある REST とは異なり、GraphQL では通常、サービスの機能の完全なセットを表す単一のエンドポイントを公開します。 単一エンドポイント : サーバー側では、リゾルバーはクエリに記述されたデータを収集します。 リゾルバー : GraphQL には、データのクエリだけでなく、サブスクリプションを使用したリアルタイム更新のサポートが組み込まれています。 サブスクリプションによるリアルタイム更新 : GraphQL サーバーは、サポートされている型についてクエリを実行できます。これにより、クライアントとサーバーの間に強力な契約が作成され、ツールとより適切な検証が可能になります。 イントロスペクティブ 使用例 : 帯域幅が重要なアプリケーション (特にモバイル) の場合、サーバーからフェッチされるデータを最小限に抑える必要があります。 柔軟なフロントエンド : 複数のマイクロサービスがある場合、GraphQL レイヤーを導入して、これらのサービスからのデータを統合 API に集約できます。 マイクロサービスの集約 : サブスクリプション システムを備えた GraphQL は、チャット アプリケーション、スポーツのライブ アップデートなど、リアルタイム データを必要とするアプリケーションに最適です。 リアルタイム アプリケーション : REST では、多くの場合、変更が導入されると API のバージョンを設定する必要があります。 GraphQL では、クライアントは必要なデータのみをリクエストするため、新しいフィールドや型を追加しても重大な変更は発生しません。 バージョンフリーの API 例 リクエスト GET “/graphql?query=user(id:42){ 名前 ロール { id 名 } }” 応答 { "data": { "user": { "id": 42, "name": "Alex", "role": { "id": 1, "name": "admin" } } } } ウェブソケット 単一の存続期間の長い接続を介して全二重通信チャネルを提供し、クライアントとサーバー間のリアルタイムのデータ交換を可能にします。このため、インタラクティブで高性能な Web アプリケーションに最適です。 WebSocket は、 : バイナリ フォーマット : TCP トランスポートプロトコル 主要な概念と特徴 : 従来の要求/応答モデルとは異なり、WebSocket は開いたままの全二重通信チャネルを提供し、リアルタイムのデータ交換を可能にします。 永続的な接続 : WebSocket は HTTP リクエストとして開始され、サーバーがサポートしている場合は WebSocket 接続にアップグレードされます。これは「Upgrade」ヘッダーを介して行われます。 アップグレード ハンドシェイク : 接続が確立されると、データはフレームとして送信されます。テキスト データとバイナリ データの両方をこれらのフレームを通じて送信できます。 フレーム : WebSocket を使用すると、交換ごとに新しい接続を開くオーバーヘッドなしで、クライアントとサーバー間の直接通信が可能になります。これにより、データ交換が高速化されます。 低遅延 : クライアントとサーバーの両方が独立して相互にメッセージを送信できます。 双方向 : 最初の接続後、データ フレームの送信に必要なバイト数が少なくなるため、HTTP 接続を繰り返し確立するよりもオーバーヘッドが減り、パフォーマンスが向上します。 オーバーヘッドの削減 : WebSocket はサブプロトコルと拡張機能をサポートしており、基本的な WebSocket プロトコルに加えて標準化されたカスタム プロトコルを使用できます。 プロトコルと拡張機能 使用例 : プレイヤーのアクションが他のプレイヤーに即座に反映される必要があるリアルタイム マルチプレイヤー ゲーム。 オンライン ゲーム : Google ドキュメントなどのアプリケーション。複数のユーザーが同時にドキュメントを編集し、互いの変更をリアルタイムで確認できます。 共同ツール : 株価をリアルタイムで更新する必要がある株式取引プラットフォーム。 金融アプリケーション : ソーシャル メディア プラットフォームやメッセージング アプリなど、ユーザーがリアルタイムの通知を受け取る必要があるアプリケーション。 通知 : 新しい投稿や更新がユーザーにライブでストリーミングされるニュース Web サイトまたはソーシャル メディア プラットフォーム。 ライブ フィード 例 リクエスト 「ws://site:8181」を取得します 応答 HTTP/1.1 101 スイッチングプロトコル Webhook は、特定の Web アプリケーション イベントによってトリガーされるユーザー定義の HTTP コールバックで、リアルタイムのデータ更新と異なるシステム間の統合を可能にします。 Webhook ：XML、JSON、プレーンテキスト 形式 : HTTP/HTTPS トランスポートプロトコル 主要な概念と特徴 : Webhook は通常、イベントが発生したことを示すために使用されます。 Webhook は定期的にデータをリクエストするのではなく、発生したときにデータを提供し、従来のリクエストとレスポンスのモデルをひっくり返します。 イベント駆動型 : Webhook は基本的にユーザー定義のコールバック メカニズムです。特定のイベントが発生すると、ソース サイトはターゲット サイトによって提供された URI への HTTP コールバックを実行し、ターゲット サイトが特定のアクションを実行します。 コールバック メカニズム : Webhook がトリガーされると、ソース サイトはデータ (ペイロード) をターゲット サイトに送信します。このデータは通常、JSON または XML の形式です。 ペイロード : Webhook を使用すると、アプリケーションはリアルタイム データを取得できるため、応答性が高くなります。 リアルタイム : ユーザーまたは開発者は通常、通知を受け取りたい特定のイベントを定義できます。 カスタマイズ可能 : Webhook にはユーザー定義の HTTP エンドポイントへのコールバックが含まれるため、セキュリティ上の問題が生じる可能性があります。エンドポイントが安全であり、データが検証され、場合によっては暗号化されていることを確認することが重要です。 セキュリティ 使用例 : コードがプッシュされるか、プル リクエストがマージされると、ビルドとデプロイメントがトリガーされます。 継続的インテグレーションとデプロイメント (CI/CD) : コンテンツが更新、公開、または削除されたときにダウンストリーム システムに通知します。 コンテンツ管理システム (CMS) : 支払いの成功、取引の失敗、返金などの取引結果について電子商取引プラットフォームに通知します。 ペイメントゲートウェイ : ソーシャルメディアプラットフォーム上の新しい投稿、メンション、またはその他の関連イベントに関する通知を受け取ります。 ソーシャルメディア統合 : デバイスまたはセンサーは Webhook をトリガーして、特定のイベントまたはデータ読み取りについて他のシステムまたはサービスに通知できます。 IoT (モノのインターネット) 例 リクエスト 「 」を取得します。 https://external-site/webhooks?url=http://site/service-h/api&name=name 応答 { "webhook_id": 12 } RPC と gRPC (リモート プロシージャ コール) は、プログラムが別のアドレス空間でプロシージャまたはサブルーチンを実行できるようにするプロトコルであり、分散システム間のシームレスな通信とデータ交換を可能にします。 RPC (Google RPC) は、RPC 上に構築された最新のオープンソース フレームワークで、トランスポートに HTTP/2 を使用し、インターフェイス記述言語としてプロトコル バッファーを使用し、効率的で堅牢な通信を促進するための認証、ロード バランシングなどの機能を提供します。マイクロサービス間。 gRPC RPC : JSON、XML、Protobuf、Thrift、FlatBuffers 形式 ：各種 トランスポートプロトコル 主要な概念と特徴 : RPC により、プログラムは別のアドレス空間 (通常は共有ネットワーク上の別のコンピューター上) でプロシージャ (サブルーチン) を実行できます。これは、呼び出し元のマシンとは別のマシンで実行される関数を呼び出すようなものです。 定義 : RPC のコンテキストでは、スタブは、ローカルとリモートのプロシージャ呼び出しを同じように見せるためのツールによって生成されるコードの一部です。クライアントにはリモート プロシージャに似たスタブがあり、サーバーには引数をアンパックし、実際のプロシージャを呼び出し、結果をパックして送り返すスタブがあります。 スタブ : 従来の RPC 呼び出しはブロックされています。つまり、クライアントはサーバーにリクエストを送信し、サーバーからの応答を待ってブロックされます。 デフォルトで同期 : 多くの RPC システムでは、記述されている言語に関係なく、さまざまなクライアントとサーバーの実装が通信できるようになります。 言語中立 : RPC では、多くの場合、クライアントとサーバーが、呼び出されるプロシージャ、そのパラメータ、および戻り値の型を認識している必要があります。 密結合 使用例 : RPC は、システムの一部が異なるマシンまたはネットワークに分散しているものの、ローカルであるかのように通信する必要がある分散システムで一般的に使用されます。 分散システム : NFS (ネットワーク ファイル システム) は、ファイル操作をリモートで実行する RPC の一例です。 ネットワーク ファイル システム 例 リクエスト { "method": "addUser", "params": [ "Alex" ] } 応答 { "id": 42, "name": "Alex", "error": null } gRPC : プロトバッファ フォーマット : HTTP/2 トランスポートプロトコル 主要な概念と特徴 : gRPC は、Google によって開発されたオープンソースの RPC フレームワークです。トランスポートには HTTP/2 を使用し、インターフェース記述言語としてプロトコル バッファー (Protobuf) を使用し、認証、負荷分散機能などを提供します。 定義 : これは、構造化データをシリアル化するための、言語中立、プラットフォーム中立の拡張可能なメカニズムです。 gRPC では、Protobuf を使用してサービス メソッドとメッセージ タイプを定義します。 プロトコル バッファー : gRPC は、低遅延かつ高スループットの通信向けに設計されています。 HTTP/2 では、単一の接続上で複数の呼び出しを多重化でき、オーバーヘッドが削減されます。 パフォーマンス : gRPC はストリーミング リクエストとレスポンスをサポートしており、長時間接続やリアルタイム更新などのより複雑なユースケースを可能にします。 ストリーミング : gRPC では、クライアントが RPC の完了を待つ時間を指定できます。サーバーはこれを確認し、操作を完了するか、時間がかかりすぎる可能性がある場合は中止するかを決定できます。 Deadlines/Timeouts : gRPC は、プラグ可能な認証、負荷分散、再試行などをサポートするように設計されています。 Pluggable : RPC と同様、gRPC は言語に依存しません。ただし、Protobuf と gRPC ツールを使用すると、複数の言語でクライアント コードとサーバー コードを生成するのが簡単になります。 言語中立 使用例 : gRPC は、そのパフォーマンス特性とサービス コントラクトを簡単に定義できる機能により、マイクロサービス アーキテクチャでよく使用されます。 マイクロサービス : gRPC はストリーミングをサポートしているため、サーバーがリアルタイムでクライアントにデータをプッシュするリアルタイム アプリケーションに適しています。 リアルタイム アプリケーション : gRPC のパフォーマンス上の利点とストリーミング機能により、バックエンド サービスと通信するモバイル クライアントに最適です。 モバイル クライアント 例 message User { int id = 1 string name = 2 } service UserService { rpc AddUser(User) returns (User); } 石鹸 は Simple Object Access Protocol の略で、コンピュータ ネットワークで Web サービスを実装するために構造化された情報を交換するためのプロトコルです。これは、異なるオペレーティング システム上で実行されているプログラムが相互に通信できるようにする XML ベースのプロトコルです。 SOAP : XML 形式 : HTTP/HTTPS、JMS、SMTP など トランスポート プロトコル 主要な概念と特徴 : SOAP メッセージは XML でフォーマットされ、次の要素が含まれます。 XML ベース : XML ドキュメントを SOAP メッセージとして定義する SOAP メッセージのルート要素。 Envelope : 中間点または最終エンドポイントでメッセージを処理する際に使用されるメッセージのオプションの属性が含まれます。 Header : 送信されるメッセージを構成する XML データが含まれます。 Body : メッセージの処理中のエラーに関する情報を提供するオプションの Fault 要素。 Fault : SOAP は任意のプログラミング モデルで使用でき、特定のプログラミング モデルに関連付けられません。 中立性 : あらゆるオペレーティング システムおよび言語で実行できます。 独立性 : クライアントからサーバーへの各リクエストには、リクエストを理解して処理するために必要なすべての情報が含まれている必要があります。 ステートレス : SOAP メッセージの Fault 要素は、エラー報告に使用されます。 組み込みエラー処理 : SOAP 仕様自体に加え、メッセージ配信を保証するための WS-ReliableMessaging、メッセージ セキュリティのための WS-Security などの関連標準を含む、明確に定義された標準に基づいて動作します。 標準化 使用例 : SOAP は、その堅牢性、拡張性、およびファイアウォールやプロキシを通過する機能により、企業環境でよく使用されます。 エンタープライズ アプリケーション : 多くの Web サービス、特に古い Web サービスは SOAP を使用します。これには、Microsoft や IBM などの大手企業が提供するサービスが含まれます。 Web サービス : SOAP にはセキュリティと拡張性が組み込まれているため、データの整合性とセキュリティが最重要視される金融取引に適しています。 金融取引 : 電気通信会社は、さまざまなシステムが確実に通信する必要がある請求などのプロセスに SOAP を使用する場合があります。 電気通信 例 リクエスト Alex 応答 42 Alex 結論 API アーキテクチャ スタイルの状況は多様であり、REST、SOAP、RPC などのさまざまなアプローチを提供しており、それぞれに独自の強みとユースケースがあるため、開発者は、異なるソフトウェア間のスケーラブルで効率的かつ堅牢な統合を構築するための最適なパラダイムを選択できます。コンポーネントとシステム。