リソース指向の設計

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

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

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

インターネット上では、HTTP REST API が広く普及してきました。2010 年には公開ネットワーク API の約 74% が HTTP REST（または REST ライク）API であり、それらのほとんどが JSON をワイヤ形式として利用していました。

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

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

REST API とは

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

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

設計フロー

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

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

リソース

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

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

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

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

メソッド

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

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/*

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/*

はじめに

リソース名