Web API成熟度モデル

# はじめに

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

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

- [RestfulなAPI](https://qiita.com/yosariii/items/9b29dc4a44bdea87f607)
- [RESTとは何か](https://qiita.com/aosho235/items/125af74e2eab66c7a816)

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

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

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

# 成熟度モデル

## Richardson Maturity Model

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

しかし、悲しいかな原著より[Martin Fowler](https://martinfowler.com/articles/richardsonMaturityModel.html)の解説記事のほうがよく引用される。まぁわかりやすいので。

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

> ![overview.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/114392/29959d62-297a-9f43-3c66-64977475c38a.png)
> 
> 出典：[Fowler, Martin. Richardson Maturity Model, 2010](https://martinfowler.com/articles/richardsonMaturityModel.html)

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

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

出典：[RESTとは何か](https://qiita.com/aosho235/items/125af74e2eab66c7a816)

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](https://en.wikipedia.org/wiki/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つの成熟度のレベルがある。それは次の図で表される。

> ![Screenshot from 2020-04-30 18-41-36.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/114392/23659e65-fbad-ae1b-9821-a8a71db0fcd1.png)
> 
> 出典：[Amundsen, Mike. Web API Design Maturity Model, 2017](http://www.amundsen.com/talks/2017-07-chattanooga/index.html)

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

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

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

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

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

どういうことか。

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

```shell:Request
DELETE http://hogehoge/internal-data
```

```shell: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を作りたいものである。