リソース指向の設計

この設計ガイドは、デベロッパーが、シンプルで整合性があり、使いやすいネットワーク API を設計するために役立ちます。また、ソケットベースの RPC API と HTTP ベースの REST API の設計を統合する場合にも役立ちます。

RPC API は、多くの場合、インターフェースとメソッドの観点から設計されています。これらが追加されるにつれ、デベロッパーが各メソッドを個別に学習する必要が生じるため、負荷が大きく混乱しやすい API サーフェスになる可能性があります。これによって、膨大な時間がかかり、エラーが発生しやすくなることは明白です。

REST のアーキテクチャ スタイルは、主に HTTP/1.1 でうまく動作するように設計されていますが、この問題への対処にも役立ちます。そのコア原則は、少数のメソッドを使用して操作可能な名前付きリソースを定義することです。リソースとメソッドはそれぞれ、API の「名詞」、「動詞」と呼ばれます。HTTP プロトコルでは、リソース名は URL に必然的にマッピングされ、メソッドは HTTP メソッド POSTGETPUTPATCHDELETE に必然的にマッピングされます。これにより、デベロッパーはリソースとその関係に集中し、それらが同じ少数の標準メソッドを持つと想定できるため、学習する内容がはるかに少なくて済みます。

インターネット上では、最近になって HTTP REST API が広く普及してきました。2010 年には、公開ネットワーク API の約 74% が HTTP REST API でした。

HTTP REST API はインターネット上で広く普及しているものの、そのトラフィック量は従来の RPC API を下回ります。たとえば、ピーク時におけるアメリカのインターネット トラフィックの約半分は動画コンテンツであり、パフォーマンス上の理由から、このようなコンテンツの配信に REST API が使用されることはほとんどありません。データセンター内部では、多くの企業がソケットベースの RPC API を使用してほとんどのネットワーク トラフィックを処理しています。これは、公開 REST API よりもはるかに大量である可能性があります。

実際には、さまざまな理由から、RPC API と HTTP REST API の両方が必要です。API プラットフォームでは、すべての API に最適なサポートを提供することが理想的です。この設計ガイドは、この原則に準拠した API を設計して構築するために役立ちます。そのために、このガイドでは一般的な API 設計にリソース指向の設計原則を適用し、ユーザビリティ向上のために、多くの一般的な設計パターンを定義して、複雑性を軽減します。

注: この設計ガイドでは、プログラミング言語、オペレーティング システム、ネットワーク プロトコルから独立して、REST 原則を API 設計に適用する方法について説明します。これは、REST API を作成するためだけのガイドではありません。

REST API とは

REST API は、個別にアドレス指定可能なリソース(API の名詞)のコレクションとしてモデル化されます。リソースはそのリソース名で参照され、少数のメソッド(動詞やオペレーションとも呼ばれる)によって操作されます。

REST Google API の標準メソッド(REST メソッドとも呼ばれる)は、ListGetCreateUpdateDelete です。API デザイナーは、データベース トランザクションなど、いずれかの標準メソッドに簡単にマッピングできない機能について、カスタム メソッド(カスタム動詞やカスタム オペレーションとも呼ばれる)を使用することもできます。

注: カスタム動詞は、カスタム メソッドをサポートするカスタム HTTP 動詞を作成するという意味ではありません。HTTP ベースの API の場合、カスタム動詞は、最適な HTTP 動詞に単純にマッピングされます。

設計フロー

設計ガイドでは、リソース指向の API を設計するとき、次の手順に従うことを推奨しています(詳細については、後述の特定のセクションをご覧ください)。

  • API で提供するリソースのタイプを決定する。
  • リソース間の関係を決定する。
  • タイプと関係に基づいてリソース名のスキームを決定する。
  • リソース スキーマを決定する。
  • 最小限の一連のメソッドをリソースにアタッチする。

リソース

通常、リソース指向の API は、各ノードがシンプル リソースかコレクション リソースのいずれかで構成されるリソース階層としてモデル化されます。便宜上、通常はこれらをそれぞれリソースとコレクションと呼びます。

  • コレクションには、同じタイプのリソースのリストが含まれます。たとえば、ユーザーは連絡先のコレクションを持ちます。
  • リソースは、なんらかの状態と 0 個以上のサブリソースを持ちます。各サブリソースは、シンプル リソースかコレクション リソースのいずれかになります。

たとえば、Gmail API にはユーザーのコレクションがあり、各ユーザーはメッセージのコレクション、スレッドのコレクション、ラベルのコレクション、プロファイル リソース、複数の設定リソースを持ちます。

ストレージ システムと REST API の間でなんらかの概念的な調整は行われるものの、リソース指向の API を含むサービスは必ずしもデータベースではなく、リソースやメソッドは非常に柔軟に解釈されます。たとえば、カレンダー イベント(リソース)を作成する場合、参加者用の追加イベントを作成して参加者にメールの招待状を送信し、会議室を予約してビデオ会議のスケジュールを更新することができます。

メソッド

リソース指向の API の主な特徴は、リソースに対して実行されるメソッド(機能)よりもリソース(データモデル)が重視されることです。一般的なリソース指向の API では、多数のリソースと少数のメソッドが公開されます。これらのメソッドは、標準メソッドかカスタム メソッドのいずれかになります。このガイドでの標準メソッドは、ListGetCreateUpdateDelete です。

API 機能がいずれかの標準メソッドに必然的にマッピングされる場合、API 設計内ではそのメソッドを使用することが推奨されます。必然的にマッピングされる標準メソッドがない機能については、カスタム メソッドを使用できます。従来の RPC API を使用すると、データベース トランザクションやデータ分析などの一般的なプログラミング パターンを実装できますが、カスタムメソッドを使用することで、設計に同様の自由度がもたらされます。

以降では、リソース指向の API 設計を大規模なサービスに適用する方法について、いくつかの実例を示します。その他の例については、Google API リポジトリをご覧ください。

以下の例では、アスタリスクはリストの中の 1 つの特定のリソースを示しています。

Gmail API

Gmail API サービスにより Gmail API が実装され、ほとんどの Gmail 機能が公開されます。これには、次のリソースモデルが含まれます。

  • API サービス: gmail.googleapis.com
    • ユーザーのコレクション: users/*。各ユーザーには次のリソースが含まれます。
      • メッセージのコレクション: users/*/messages/*
      • スレッドのコレクション: users/*/threads/*
      • ラベルのコレクション: users/*/labels/*
      • 変更履歴のコレクション: users/*/history/*
      • ユーザー プロファイルを表すリソース: users/*/profile
      • ユーザー設定を表すリソース: users/*/settings

Cloud Pub/Sub API

pubsub.googleapis.com サービスにより、次のリソースモデルを定義する Cloud Pub/Sub API が実装されます。

  • API サービス: pubsub.googleapis.com
    • トピックのコレクション: projects/*/topics/*
    • サブスクリプションのコレクション: projects/*/subscriptions/*

注: Pub/Sub API のその他の実装では、異なるリソース命名スキームを選択できます。

Cloud Spanner API

spanner.googleapis.com サービスにより、次のリソースモデルを定義する Cloud Spanner API が実装されます。

  • API サービス: spanner.googleapis.com
    • インスタンスのコレクション: projects/*/instances/*
      • インスタンス オペレーションのコレクション: projects/*/instances/*/operations/*
      • データベースのコレクション: projects/*/instances/*/databases/*
      • データベース オペレーションのコレクション: projects/*/instances/*/databases/*/operations/*
      • データベース セッションのコレクション: projects/*/instances/*/databases/*/sessions/*
このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...