はじめに

Web API成熟度モデルについてまとめる。

Web API成熟度モデルを解説した日本語のサイトはすでにいくつかある。

しかし、これらのサイトで解説されているモデルは2009年にRichardson氏が提唱したRichardson Maturity Model(RMM)だけ。

実は、2017年にAmundsen氏が新たな成熟度モデル、Web API Design Maturity Model(WADM)を提唱している。Amundsen氏は、O'REILLYでMicroservice Architectureを上梓した方で、マイクロサービスにも造詣が深い。

ここでは2つの成熟度モデルを紹介し、その違いをまとめる。

成熟度モデル

Richardson Maturity Model

Richardson Maturity Model(RMM)は、文字通りRichardson氏が2009年に提唱した成熟度モデルである。

しかし、悲しいかな原著よりMartin Fowlerの解説記事のほうがよく引用される。まぁわかりやすいので。

RMMの成熟度には、次の4つのレベルがある。

出典：Fowler, Martin. Richardson Maturity Model, 2010

これらの成熟度は、以下のように定義される。

Level 0 Plain Old XML（昔ながらの単純にXMLを返すやり方）
Level 1 URLでリソースを表すようにする（リソースを動詞でなく名詞で表す）
Level 2 HTTPメソッドGET, POST, PUT, DELETE等を正しく使い分ける
Level 3 レスポンスの中に関連するリンクを含める

出典：RESTとは何か

Amundsen氏いわく、Richardson氏はRMMを特定の技術(specific technologies)に着目して定義した、とのことである。前述のLevelの定義を技術の側面でまとめ直したものが、以下である。

Level 0 URLだけ
Level 1 URL + Resource
Level 2 URL + Resource + HTTP Method
Level 3 URL + Resource + HTTP Method + Hyperlink = HATEOAS

すなわち、Level 0はURLを使っていても中身は昔ながらのXML。
Level 1はResource別にURLを実装してはいてもHTTP Methodは使いこなせていない。
Level 2はHTTP Methodも使いこなせているが、HATEOASにはなっていない。
Level 3はHATEOASになっている。

Web API Design Maturity Model

Web API Design Maturity Model(WADM)は、2017年にAmundsen氏が提唱した成熟度モデルである。

当然、RMMを熟知した上で提唱しているモデルなので、大枠はよく似ている。

WADMにも、4つの成熟度のレベルがある。それは次の図で表される。

出典：Amundsen, Mike. Web API Design Maturity Model, 2017

これらの成熟度は、以下のように定義される。

Level 0 データベース中心：JSONなどのマナの内部用データをそのまま外部にさらす
Level 1 オブジェクト中心：XSDなどでデータ構造を定義した内部用データを外部にさらす
Level 2 リソース中心：リソース毎に整理した外部用データを外部にさらす
Level 3 アフォーダンス中心：内部データ構造とは完全に分離した外部用データを外部にさらす = HATEOAS

成熟度は、Level0,1とLevel2,3大別され、前者は内部用データをそのまま、後者は外部用に整理されたデータをAPIとして外部にさらす点が異なる。当然ながら外部用データにまとめたほうが、APIとしての成熟度は高い。

一方、Level0,1の違いはXSD等のメタデータ定義をしっかりしているかどうかの違いである。また、Level2,3の違いは、HATEOASになっているかどうかの違いである。

Amundsen氏によれば、WADMは設計に着目した成熟度モデルである。そこにRMMとの決定的な違いがある。

どういうことか。

たとえば、次のようなREST APIを考える。

Request

DELETE http://hogehoge/internal-data

Response

HTTP/1.1 200 OK 
Date: Wed, 21 Oct 2015 07:28:00 GMT

OK

RMM の観点で言えば、一応 Level2になっていると言えるだろう。形式的にはURLでResourceを表現し、HTTP Methodを正しく使っているからだ。

しかし、そもそも内部用データinternal-dataを外部から削除できてよいのだろうか？おかしくないか？

ここで登場するのがWADMである。WADMの観点でいえば、これはLevel 0と言える。なぜなら、これは単にマナの内部用データをそのまま外部にさらしているだけだからである。

このように、設計の観点からAPIの成熟度を考えたのがWADMである。

まとめ

2つの成熟度モデルをざっくりまとめると次のようになる。

項目	RMM	WADM
成熟度レベルの数	4	4
Level 0	URL Only	データベース中心
Level 1	Level 0 + Resource	オブジェクト中心
Level 2	Level 1 + HTTP Method	リソース中心
Level 3	Level 2 + Hyperlink	アフォーダンス中心
完全に成熟した状態	HATEOAS	HATEOAS
着眼点	実装	設計、思想

どちらのモデルも4段階あり、最終的な成熟段階としてはHATEOASを指向している点に共通点がある。

一方で、RMMはSOAPやHTTP等の実装技術に着眼し、WADMは設計に主眼をおいていた点が異なっている。

それぞれの成熟度モデルは相補的なものであり、両方の観点で良いAPIを作りたいものである。