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

これは、システム アーキテクチャ設計における特定のトピックの要点を簡単に説明する一連の記事の続きです。最初の記事はここから読めます

API アーキテクチャとは、ソフトウェア コンポーネントがどのように対話するかを決定する一連のルール、プロトコル、およびツールを指します。 API のアーキテクチャは、通信を容易にするだけではありません。また、この通信が効率的、安全、スケーラブルであることを保証することも重要です。

適切に設計された API アーキテクチャはシステムのパフォーマンスを大幅に向上させることができますが、設計が不十分な API アーキテクチャはボトルネック、セキュリティの脆弱性、メンテナンスの悪夢につながる可能性があります。

さまざまなスタイルの API アーキテクチャ

最も一般的な API 設計スタイルは次のとおりです。

1. REST (Representational State Transfer) は、標準メソッドと HTTP プロトコルを使用する最もよく使用されるスタイルです。これは、ステートレス性、クライアント/サーバー アーキテクチャ、キャッシュ可能性などの原則に基づいています。フロントエンド クライアントとバックエンド サービスの間でよく使用されます。

   
   

2. GraphQLは API 用のクエリ言語です。リソースごとにエンドポイントの固定セットを公開する REST とは異なり、GraphQL ではクライアントが必要なデータを正確にリクエストできるため、オーバーフェッチが削減されます。

   
   

3. WebSocketは、TCP 経由の双方向通信を可能にするプロトコルです。クライアントは Web ソケットを使用して、バックエンド システムからリアルタイムの更新を取得します。

   
   

4. Webhook は、あるシステムが別のシステムに特定のイベントについてリアルタイムで通知できるようにするメカニズムです。これはユーザー定義の HTTP コールバックです。

   
   

5. RPC (gRPC) は、あるサービスがネットワーク内の別のコンピューターにあるサービスからプロシージャ/メソッドを要求するために使用できるプロトコルです。通常、低遅延、高速通信向けに設計されています。

   
   

6. SOAP は、 Web サービスを実装するために構造化された情報を交換するためのプロトコルです。 XML に依存しており、堅牢性とセキュリティ機能で知られていますが、現在はレガシー プロトコルと考えられています。

各プロトコルの長所、短所、使用例を個別に見てみましょう。

休む

RESTは、標準的な規則とプロトコルを使用するアーキテクチャ スタイルであり、理解しやすく、実装しやすくなっています。ステートレスな性質と標準 HTTP メソッドの使用により、Web ベースの API を構築するための一般的な選択肢となっています。

REST は長い間 API を構築するための事実上の標準でしたが、GraphQL のような他のスタイルも登場し、データのクエリと操作のためのさまざまなパラダイムを提供しています。

形式: XML、JSON、HTML、プレーンテキスト

トランスポートプロトコル: HTTP/HTTPS

主要な概念と特徴

• リソース: REST では、すべてがリソースです。リソースは、タイプ、関連データ、他のリソースとの関係、およびリソース上で動作する一連のメソッドを持つオブジェクトです。リソースは、その URI (通常は URL) によって識別されます。

  
  

• CRUD 操作: REST サービスは多くの場合、リソースに対する CRUD (作成、読み取り、更新、削除) 操作に直接マップされます。

  
  

• HTTP メソッド: REST システムは標準の 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 はクライアントサーバーモデルに基づいています。クライアントはユーザー インターフェイスとエクスペリエンスを担当し、サーバーはリクエストの処理、ビジネス ロジックの処理、およびデータの保存を担当します。

  
  

• キャッシュ可能: サーバーからの応答をクライアントがキャッシュできます。サーバーは、応答がキャッシュ可能かどうかを示す必要があります。

  
  

• 階層化システム: 通常、クライアントは、エンド サーバーに直接接続されているのか、仲介サーバーに接続されているのかを知ることができません。中間サーバーは、負荷分散を有効にし、共有キャッシュを提供することにより、システムのスケーラビリティを向上させることができます。

  
  

• HATEOAS:アプリケーションのエンジンとしてのハイパーメディア Stat は、サーバーが応答で動的に提供するハイパーメディアに完全に基づいてクライアントが Web アプリケーションと対話し、ナビゲートできるようにする REST Web サービスの原則であり、疎結合と検出可能性を促進します。

使用例

• Web サービス: 多くの Web サービスは REST API 経由で機能を公開しており、サードパーティの開発者がサービスを統合および拡張できるようにしています。

• モバイル アプリケーション: モバイル アプリケーションは、多くの場合、REST API を使用してバックエンド サーバーと通信し、データを取得および送信します。

• シングル ページ アプリケーション (SPA) : SPA は REST API を使用して、ページ全体を更新することなくコンテンツを動的に読み込みます。

• システム間の統合:組織内のシステムは、REST API を使用して通信し、データを共有できます。

例

リクエスト

「/user/42」を取得

応答

{ "id": 42, "name": "Alex", "links": { "role": "/user/42/role" } }

グラフQL

GraphQL は、特に複雑なシステムやフロントエンドに高い柔軟性が必要な場合に、API を構築するためのより柔軟で堅牢かつ効率的なアプローチを提供します。これにより、責任の一部がサーバーからクライアントに移され、クライアントがデータ要件を指定できるようになります。

すべてのシナリオで REST に代わるわけではありませんが、特にアプリケーションのネットワーク化と分散化が進むにつれて、多くの状況で魅力的な代替手段となります。

形式: JSON

トランスポートプロトコル: HTTP/HTTPS

主要な概念と特徴

• API のクエリ言語: クライアントが必要なデータをリクエストできるようになり、必要なすべての情報を 1 回のリクエストで取得できるようになります。

• タイプ システム: GraphQL API は、エンドポイントではなく、タイプとフィールドの観点から編成されています。強力な型システムを使用して API の機能を定義します。 API で公開されるすべての型は、GraphQL スキーマ定義言語 (SDL) を使用してスキーマに書き込まれます。

• 単一エンドポイント: さまざまなリソースに複数のエンドポイントがある REST とは異なり、GraphQL では通常、サービスの機能の完全なセットを表す単一のエンドポイントを公開します。

• リゾルバー: サーバー側では、リゾルバーはクエリに記述されたデータを収集します。

• サブスクリプションによるリアルタイム更新: GraphQL には、データのクエリだけでなく、サブスクリプションを使用したリアルタイム更新のサポートが組み込まれています。

• イントロスペクティブ: GraphQL サーバーは、サポートされている型についてクエリを実行できます。これにより、クライアントとサーバーの間に強力な契約が作成され、ツールとより適切な検証が可能になります。

使用例

• 柔軟なフロントエンド: 帯域幅が重要なアプリケーション (特にモバイル) の場合、サーバーからフェッチされるデータを最小限に抑える必要があります。

• マイクロサービスの集約: 複数のマイクロサービスがある場合、GraphQL レイヤーを導入して、これらのサービスからのデータを統合 API に集約できます。

• リアルタイム アプリケーション: サブスクリプション システムを備えた GraphQL は、チャット アプリケーション、スポーツのライブ アップデートなど、リアルタイム データを必要とするアプリケーションに最適です。

• バージョンフリーの API : REST では、多くの場合、変更が導入されると API のバージョンを設定する必要があります。 GraphQL では、クライアントは必要なデータのみをリクエストするため、新しいフィールドや型を追加しても重大な変更は発生しません。

例

リクエスト

GET “/graphql?query=user(id:42){ 名前 ロール { id 名 } }”

応答

{ "data": { "user": { "id": 42, "name": "Alex", "role": { "id": 1, "name": "admin" } } } }

ウェブソケット

WebSocket は、単一の存続期間の長い接続を介して全二重通信チャネルを提供し、クライアントとサーバー間のリアルタイムのデータ交換を可能にします。このため、インタラクティブで高性能な Web アプリケーションに最適です。

フォーマット: バイナリ

トランスポートプロトコル: TCP

主要な概念と特徴

• 永続的な接続: 従来の要求/応答モデルとは異なり、WebSocket は開いたままの全二重通信チャネルを提供し、リアルタイムのデータ交換を可能にします。

• アップグレード ハンドシェイク: WebSocket は HTTP リクエストとして開始され、サーバーがサポートしている場合は WebSocket 接続にアップグレードされます。これは「Upgrade」ヘッダーを介して行われます。

• フレーム: 接続が確立されると、データはフレームとして送信されます。テキスト データとバイナリ データの両方をこれらのフレームを通じて送信できます。

• 低遅延: WebSocket を使用すると、交換ごとに新しい接続を開くオーバーヘッドなしで、クライアントとサーバー間の直接通信が可能になります。これにより、データ交換が高速化されます。

• 双方向: クライアントとサーバーの両方が独立して相互にメッセージを送信できます。

• オーバーヘッドの削減: 最初の接続後、データ フレームの送信に必要なバイト数が少なくなるため、HTTP 接続を繰り返し確立するよりもオーバーヘッドが減り、パフォーマンスが向上します。

• プロトコルと拡張機能: WebSocket はサブプロトコルと拡張機能をサポートしており、基本的な WebSocket プロトコルに加えて標準化されたカスタム プロトコルを使用できます。

使用例

• オンライン ゲーム: プレイヤーのアクションが他のプレイヤーに即座に反映される必要があるリアルタイム マルチプレイヤー ゲーム。

• 共同ツール: Google ドキュメントなどのアプリケーション。複数のユーザーが同時にドキュメントを編集し、互いの変更をリアルタイムで確認できます。

• 金融アプリケーション: 株価をリアルタイムで更新する必要がある株式取引プラットフォーム。

• 通知: ソーシャル メディア プラットフォームやメッセージング アプリなど、ユーザーがリアルタイムの通知を受け取る必要があるアプリケーション。

• ライブ フィード: 新しい投稿や更新がユーザーにライブでストリーミングされるニュース Web サイトまたはソーシャル メディア プラットフォーム。

例

リクエスト

「ws://site:8181」を取得します

応答

HTTP/1.1 101 スイッチングプロトコル

Webhook

Webhookは、特定の Web アプリケーション イベントによってトリガーされるユーザー定義の HTTP コールバックで、リアルタイムのデータ更新と異なるシステム間の統合を可能にします。

形式：XML、JSON、プレーンテキスト

トランスポートプロトコル: HTTP/HTTPS

主要な概念と特徴

• イベント駆動型: Webhook は通常、イベントが発生したことを示すために使用されます。 Webhook は定期的にデータをリクエストするのではなく、発生したときにデータを提供し、従来のリクエストとレスポンスのモデルをひっくり返します。

• コールバック メカニズム: Webhook は基本的にユーザー定義のコールバック メカニズムです。特定のイベントが発生すると、ソース サイトはターゲット サイトによって提供された URI への HTTP コールバックを実行し、ターゲット サイトが特定のアクションを実行します。

• ペイロード: Webhook がトリガーされると、ソース サイトはデータ (ペイロード) をターゲット サイトに送信します。このデータは通常、JSON または XML の形式です。

• リアルタイム: Webhook を使用すると、アプリケーションはリアルタイム データを取得できるため、応答性が高くなります。

• カスタマイズ可能: ユーザーまたは開発者は通常、通知を受け取りたい特定のイベントを定義できます。

• セキュリティ: Webhook にはユーザー定義の HTTP エンドポイントへのコールバックが含まれるため、セキュリティ上の問題が生じる可能性があります。エンドポイントが安全であり、データが検証され、場合によっては暗号化されていることを確認することが重要です。

使用例

• 継続的インテグレーションとデプロイメント (CI/CD) : コードがプッシュされるか、プル リクエストがマージされると、ビルドとデプロイメントがトリガーされます。

• コンテンツ管理システム (CMS) : コンテンツが更新、公開、または削除されたときにダウンストリーム システムに通知します。

• ペイメントゲートウェイ: 支払いの成功、取引の失敗、返金などの取引結果について電子商取引プラットフォームに通知します。

• ソーシャルメディア統合: ソーシャルメディアプラットフォーム上の新しい投稿、メンション、またはその他の関連イベントに関する通知を受け取ります。

• IoT (モノのインターネット) : デバイスまたはセンサーは Webhook をトリガーして、特定のイベントまたはデータ読み取りについて他のシステムまたはサービスに通知できます。

例

リクエスト

「 https://external-site/webhooks?url=http://site/service-h/api&name=name 」を取得します。

応答

{ "webhook_id": 12 }

RPC と gRPC

RPC (リモート プロシージャ コール) は、プログラムが別のアドレス空間でプロシージャまたはサブルーチンを実行できるようにするプロトコルであり、分散システム間のシームレスな通信とデータ交換を可能にします。

gRPC (Google RPC) は、RPC 上に構築された最新のオープンソース フレームワークで、トランスポートに HTTP/2 を使用し、インターフェイス記述言語としてプロトコル バッファーを使用し、効率的で堅牢な通信を促進するための認証、ロード バランシングなどの機能を提供します。マイクロサービス間。

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 はストリーミング リクエストとレスポンスをサポートしており、長時間接続やリアルタイム更新などのより複雑なユースケースを可能にします。

• Deadlines/Timeouts : gRPC では、クライアントが RPC の完了を待つ時間を指定できます。サーバーはこれを確認し、操作を完了するか、時間がかかりすぎる可能性がある場合は中止するかを決定できます。

• Pluggable : gRPC は、プラグ可能な認証、負荷分散、再試行などをサポートするように設計されています。

• 言語中立: RPC と同様、gRPC は言語に依存しません。ただし、Protobuf と gRPC ツールを使用すると、複数の言語でクライアント コードとサーバー コードを生成するのが簡単になります。

使用例

• マイクロサービス: gRPC は、そのパフォーマンス特性とサービス コントラクトを簡単に定義できる機能により、マイクロサービス アーキテクチャでよく使用されます。

• リアルタイム アプリケーション: gRPC はストリーミングをサポートしているため、サーバーがリアルタイムでクライアントにデータをプッシュするリアルタイム アプリケーションに適しています。

• モバイル クライアント: gRPC のパフォーマンス上の利点とストリーミング機能により、バックエンド サービスと通信するモバイル クライアントに最適です。

例

message User { int id = 1 string name = 2 } service UserService { rpc AddUser(User) returns (User); }

石鹸

SOAPは Simple Object Access Protocol の略で、コンピュータ ネットワークで Web サービスを実装するために構造化された情報を交換するためのプロトコルです。これは、異なるオペレーティング システム上で実行されているプログラムが相互に通信できるようにする XML ベースのプロトコルです。

形式: XML

トランスポート プロトコル: HTTP/HTTPS、JMS、SMTP など

主要な概念と特徴

• XML ベース: SOAP メッセージは XML でフォーマットされ、次の要素が含まれます。

  • Envelope : XML ドキュメントを SOAP メッセージとして定義する SOAP メッセージのルート要素。

  
  

  • Header : 中間点または最終エンドポイントでメッセージを処理する際に使用されるメッセージのオプションの属性が含まれます。

  
  

  • Body : 送信されるメッセージを構成する XML データが含まれます。

  
  

  • Fault : メッセージの処理中のエラーに関する情報を提供するオプションの Fault 要素。

    
    

• 中立性: SOAP は任意のプログラミング モデルで使用でき、特定のプログラミング モデルに関連付けられません。

• 独立性: あらゆるオペレーティング システムおよび言語で実行できます。

• ステートレス: クライアントからサーバーへの各リクエストには、リクエストを理解して処理するために必要なすべての情報が含まれている必要があります。

• 組み込みエラー処理: SOAP メッセージの Fault 要素は、エラー報告に使用されます。

• 標準化: SOAP 仕様自体に加え、メッセージ配信を保証するための WS-ReliableMessaging、メッセージ セキュリティのための WS-Security などの関連標準を含む、明確に定義された標準に基づいて動作します。

使用例

• エンタープライズ アプリケーション: SOAP は、その堅牢性、拡張性、およびファイアウォールやプロキシを通過する機能により、企業環境でよく使用されます。

• Web サービス: 多くの Web サービス、特に古い Web サービスは SOAP を使用します。これには、Microsoft や IBM などの大手企業が提供するサービスが含まれます。

• 金融取引: SOAP にはセキュリティと拡張性が組み込まれているため、データの整合性とセキュリティが最重要視される金融取引に適しています。

• 電気通信: 電気通信会社は、さまざまなシステムが確実に通信する必要がある請求などのプロセスに SOAP を使用する場合があります。

例

リクエスト

<?xml version="1.0"?> <soap:Envelope> <soap:Body> <m:AddUserRequest> <m:Name>Alex</m:Name> </m:AddUserRequest> </soap:Body> </soap:Envelope>

応答

<?xml version="1.0"?> <soap:Envelope> <soap:Body> <m:AddUserResponse> <m:Id>42</m:Id> <m:Name>Alex</m:Name> </m:AddUserResponse> </soap:Body> </soap:Envelope>

結論

API アーキテクチャ スタイルの状況は多様であり、REST、SOAP、RPC などのさまざまなアプローチを提供しており、それぞれに独自の強みとユースケースがあるため、開発者は、異なるソフトウェア間のスケーラブルで効率的かつ堅牢な統合を構築するための最適なパラダイムを選択できます。コンポーネントとシステム。