Microsoft Graphは、HTTPを使ったいわゆる「Web API」で、RESTful(レストフル)でJSONを返すという今では一般的な構造だ。

 HTTPでは、指定されたURLで示される「ホスト」のURLパスに対して要求を送り、URL側(サーバー)は、応答を戻して完結する。定義はRFC7230〜7235にある。要求や応答は、ヘッダー(header)と本文(Body)に分かれている。

HTTPとは、テキスト表現された要求に対して、応答が返るプロトコル。Webブラウザーは、応答で得たHTMLを解釈し、必要な要素(画像など)を繰り返しHTTPで取得してページをレンダリングしている。
HTTPとは、テキスト表現された要求に対して、応答が返るプロトコル。Webブラウザーは、応答で得たHTMLを解釈し、必要な要素(画像など)を繰り返しHTTPで取得してページをレンダリングしている。
[画像のクリックで拡大表示]

 要求ヘッダーには、メソッドと呼ばれるある種のコマンドがあり、サーバー側はこれに応じて応答を返す(ただし何をするのかはサーバー次第だ)。様々なメソッドがあるが、Microsoft Graphでは、「GET」「PUT」「POST」「DELETE」「PATCH」を利用している。

メソッドとその意味
メソッド意味定義
GETリソース情報の要求RFC7231
POSTリソースの新規作成RFC7231
PUTリソースの置き換えRFC7231
DELETEリソースの削除RFC7231
PATCHリソースの部分更新RFC5789
HEADMicrosoft Graphでは使われていないRFC7231
CONNECTMicrosoft Graphでは使われていないRFC7231
OPTIONSMicrosoft Graphでは使われていないRFC7231
TRACEMicrosoft Graphでは使われていないRFC7231

 Microsoft Graphでは、URLで指定されたリソースとメソッドの組み合わせでAPIを実現している。例えば、GETメソッドを使うことで、指定されたリソースが持つ情報が応答本文として戻ってくる。また、POSTメソッドはリソースの新規作成に、PUTは、リソースの置き換え、DELETEは削除、PATCHは部分更新に使われる。ただし、全てのメソッドが全てのリソースで利用できるわけではない。GET以外のメソッドはリソースごとに対応の有無と動作が決められている。

改めてRESTとは何か

 RESTfulあるいはRESTとは、「Representational State Transfer」の略で、HTTPを使ったURLによるAPIを構築する手法の一種だ。最大の特徴はステートレスで、一連のAPI呼び出しを行うセッション間で状態などを保存しないこと。状態を保存しないため、それぞれの要求に対して個別のサーバーが応答でき、サーバー間でセッションに関係する情報を共有する必要がない。このため、サーバーのスケールアウト(サーバーなどを増やして規模を拡大すること)が容易になる。

 その反面、呼び出しのパラメーターが増えたり、複雑になってしまう傾向はある。例えば、Microsoft Graphの場合、組織内の全ユーザーの一覧を取得する場合など、大量の応答を複数のページに分割して受け取ることができる。セッション間で状態が保存できる場合、2回目以降のAPI呼び出しでは、引数などを省略できることが多いが、Microsoft Graphでは、セッション間で情報を保存しないため、最初の応答に「nextLink」と呼ばれる情報が付加される。2ページ目の応答を受け取るには、このリンクを利用して再度GETメソッドを実行する。

Graphエクスプローラーで組織内の全ユーザーのdisplayNameだけを応答させたもの。多数のデータが戻されている。
Graphエクスプローラーで組織内の全ユーザーのdisplayNameだけを応答させたもの。多数のデータが戻されている。
[画像のクリックで拡大表示]
クエリー文字列でTOPを使って1回当たり5件のみを応答させるように指定。nextLinkが応答に含まれ、最初の5件の情報が来る。
クエリー文字列でTOPを使って1回当たり5件のみを応答させるように指定。nextLinkが応答に含まれ、最初の5件の情報が来る。
[画像のクリックで拡大表示]
nextLinkを使ってさらに問い合わせると、次の5件(6~10件目)が戻される。nextLinkには11~15件目を応答させるリンクが含まれている。
nextLinkを使ってさらに問い合わせると、次の5件(6~10件目)が戻される。nextLinkには11~15件目を応答させるリンクが含まれている。
[画像のクリックで拡大表示]