Richardson Maturity Model
イントロ
RESTful API設計開発の指針として、Richardson Maturity Model (以降ではRichardson成熟モデルと呼ぶ)という素晴らしいものがあります。 海外の情報リソースでは、頻繁に見かけるものの、意外と日本では見かけないので、少しメモしておきます。
Richardson成熟モデル
Richardson成熟モデルとは、Leonard Richardsonという方が、2008年のQConで発表したものです。 RESTfulを目指していくなら、以下の段階を踏んで設計を成熟させていきましょう、という指針です。
モデルの概要は、Martin Fowlerが記載したと思われるこの図に表されます。
- Level0: リモートのシステムとのインタラクションに、単にHTTPを利用しただけのAPI
- Level1: APIをシステムコールではなく、WebリソースのアクセスへとしたAPI
- Level2: 適切なHTTPメソッドを利用してリソースへのアクセス・登録等を行うAPI
- Level3: クライアントが取得したリソースから何をすれば良いかを理解するためのHATEOASをサポートしたAPI
具体的な説明は、下の参考に記載したMartin Fowlerの記事が分かりやすいと思うので、ご覧頂きたいのですが、簡単に概要を補足します。
Level 0
Level0は、Webの機能を何も使わず、RPCの代わりとして、特にポリシーもなくHTTPを使っているだけです。
ケースバイケースですが、開発組織の内部に閉じたAPIを用意するだけであれば、これだけで問題ない場合は多いかもしれません。 ただし、これだけでは何も設計方針がないに等しいので、プロダクトが拡張されていくにつれ、API設計がめちゃくちゃになる可能性は大だと思います。
APIというのは、基本的に一度提供したら変えにくいものなので、組織外のコンシューマー(APIを使う側の開発者)に提供するAPIを設計する場合は、Level 0ではマズいでしょう。
Level 1
Level1は、リソース指向の考えが加わります。
Martin Fowlerの記事では、歯医者の予約サービスを例に説明されていますが、この予約の時間帯スロットをリソースとし、アクセスしています。 予約を取る、という動詞に対するアクセスではない、ということです。
このリソース指向の感覚は、開発者間、または開発者とコンシューマーの意思疎通を円滑にするためには、おさえておいた方が良いかもしれません。
Level 2
Level2では、GETならリソースの取得、POSTなら新規登録、PUTなら更新、DELETEなら削除、と言ったメソッドに沿った処理をしましょう、ということです。
また、Level2では、HTTPのレスポンスコードをちゃんと正しく使いましょう、とも記載されています。 レスポンスコードだけで、APIに対応した処理で何が起こったら分かるように、と。
Level3
Level3では、Hypermedia Controlsという概念が加わります。
急に難しくなった感じですが、一言で言うと、「一連の業務を完結させるためにコールすべきAPIとその順序に関するsuggestionを、コンシューマーに与えてあげる」ということです。
Level 0のように、一つの業務自体に1エンドポイントという形式であれば問題はありませんが、それでは業務が変わるごとにAPIが作られて、APIエンドポイントだらけになり、APIの統一性が悪くなります。 これに対しLevel 1,2が登場するわけですが、そうなると多くの場合、一つの業務に対して何回もAPIコールを行う必要が出てきます。 Martin Fowlerの記事で言うなら、予約をする、という業務（ユーザーのやりたいこと）に対して、指定した時間帯に歯医者の予約が開いているかの問い合わせ、で1エンドポイント、予約を入れる、でもう1エンドポイント、という感じです。
その時に、Hypermedia Controlsは、「時間帯が開いているか調べたと言うことは、ユーザーはこんな作業がしたいんじゃないかな？」と解釈して、1つ目のコールのレスポンスボディに「予約を入れたいなら、次にこのエンドポイントにコールしたら良いよ」という情報を<link>タグなどで教えてあげるのです。
これは、コンシューマーにとってはかなりありがたいことです。
なぜなら、ユーザーに次の作業を行わせるためには、その<link>タグの情報を使って、ユーザーへのビューを作成すれば良く、コンシューマー自身がAPIエンドポイントについて知らなければいけない知識を減らすことが出来るためです。
さらに、APIのバージョンアップに対しても、コンシューマー自身がAPIのバージョンアップをフォローしておく必要もなくなります。
HATEOAS
こういった、WWWの思想である、リソースのつながり、というものを効果的に利用するのが、REST APIの醍醐味なのでしょう。
ちなみに、このリソースのつながり、は、一つの業務内でのアプリケーションの状態遷移と見ることが出来ると思います。 Level 3のような、このアプリケーションの状態遷移としてのHypermedia Controlsの使い方を、HATEOAS (Hypertext As The Engine Of Application State)と言います。 Martin Fowlerも言っていますが、すごい略語ですね。
