Microsoft Graphは、HTTPを使ったいわゆる「Web API」で、RESTful(レストフル)でJSONを返すという今では一般的な構造だ。
HTTPでは、指定されたURLで示される「ホスト」のURLパスに対して要求を送り、URL側(サーバー)は、応答を戻して完結する。定義はRFC7230〜7235にある。要求や応答は、ヘッダー(header)と本文(Body)に分かれている。
要求ヘッダーには、メソッドと呼ばれるある種のコマンドがあり、サーバー側はこれに応じて応答を返す(ただし何をするのかはサーバー次第だ)。様々なメソッドがあるが、Microsoft Graphでは、「GET」「PUT」「POST」「DELETE」「PATCH」を利用している。
メソッド | 意味 | 定義 |
---|---|---|
GET | リソース情報の要求 | RFC7231 |
POST | リソースの新規作成 | RFC7231 |
PUT | リソースの置き換え | RFC7231 |
DELETE | リソースの削除 | RFC7231 |
PATCH | リソースの部分更新 | RFC5789 |
HEAD | Microsoft Graphでは使われていない | RFC7231 |
CONNECT | Microsoft Graphでは使われていない | RFC7231 |
OPTIONS | Microsoft Graphでは使われていない | RFC7231 |
TRACE | Microsoft 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メソッドを実行する。