OpenAPIとは｜面の変え方5通りのうち、古い呼び手が読めるのは2通りだけだった

記述1つから、文書も呼び手も検査も作れる

人と機械の両方が読める形で書きます。だから、同じ記述から複数の道具を作れます。

OpenAPIが定めるのは、面の記述の書き方です。仕様は自らをこう定義しています。

OpenAPIの仕様は、HTTPの面に対する、標準の、プログラミング言語に依らない面の記述を定める。これにより、人も機械も、原始の記述や追加の文書、通信の中身を調べることなく、あるサービスの能力を見つけて理解できるという記述です。

「人も機械も」が要点です。機械が読めるので、そこから道具を作れます。

作れるもの

仕様は用途を列挙しています。記述は、面を表示する文書の生成の道具、さまざまな言語で受ける側と呼ぶ側を生成する道具、検査の道具、その他多くの用途に使えるという記述です。

1. 文書。記述から生成するので、実装とずれない
2. 呼ぶ側の記述。手で書かないので誤りが減る
3. 受ける側の骨格。項目の検査を自動で入れられる
4. 検査の道具。実際の応答が記述と合うか確かめる

4番目が、この記事で数える部分です。記述があれば、合っているかを機械が確かめられます。

何を書くか

仕様は記述の呼び名も定めています。OpenAPIの記述は、ある面の表面とその意味を形式的に記述するという説明です。

「表面と意味」の両方です。項目の名前と型だけでなく、必須かどうかや値の範囲まで書けます。

面の変え方5通りのうち、古い呼び手が読めるのは2通りだけ

記述があっても、変え方の制約は消えません。読めるかどうかは足す位置で決まります。

OpenAPIの記述は、面の形を固定します。仕様はOpenAPIの記述は、ある面の表面とその意味を形式的に記述すると述べています。

固定した形を変えると、古い呼び手が読めなくなることがあります。変え方ごとに整理しました。

変え方ごとの影響

形を先に決めておく方式で、あとから項目を変えた場合
古い読み手が新しい記録を読めるかを整理する

変え方              古い読み手  理由
末尾に項目を足す                   読める  知らない項目を飛ばせる形なら
途中に項目を足す                  読めない  位置で読む形では、以降がすべてずれる
項目名を変える                   読めない  名前で引く形では見つからなくなる
項目を消す                     読めない  必須として読んでいれば失敗する
既定値つきで足す                   読める  古い記録にはその値が入っているものとして扱える

読めるのは2通りです。末尾に足すか、既定値つきで足すかです。

途中に足した場合の影響も数えました。5項目のうち3項目がずれます。

記述があれば先に分かる

この表の判定は、記述どうしを比べれば機械が出せます。手で読む必要がありません。

つまり記述の値打ちは、書くことではなく比べられることにあります。前の版との差から、壊れる変更を見つけられます。

同じ考え方を、表の列に対して適用したのがデータ契約の記事です。形が変わらないまま意味だけ変わる場合は、どちらでも検出できません。

確認を足していくと、検出率が段で上がる

記述は検査の基準になります。ただし、確認を落とした分はそのまま通り抜けます。

OpenAPIで正しく定義されていれば、呼ぶ側の実装は軽くなります。仕様はOpenAPIによって適切に定義されていれば、利用する側は最小限の実装の論理で、離れたサービスを理解しやりとりできると述べています。

「適切に定義されていれば」が前提です。定義と実際が合っているかは、別に確かめることになります。

確認を1つずつ足す

確認を足したときに何が止まるかを、別の題材で数えた結果が参考になります。券5000枚のうち1983枚に細工をした場合です。

券 5000枚。うち細工したもの 1983枚（39.7%）
確認を1つずつ足していったときに、何枚を止められるか

足した確認                    止めた枚数  正しく止めた  誤って止めた  検出率
形として読めるか                            0枚            0枚            0枚     0.0%
署名の方式が想定通りか                       287枚          287枚            0枚    14.5%
署名が合っているか                         844枚          844枚            0枚    42.6%
発行元が合っているか                       1119枚         1119枚            0枚    56.4%
宛先が自分か                           1397枚         1397枚            0枚    70.4%
期限が切れていないか                       1668枚         1668枚            0枚    84.1%
合言葉が使い回しでないか                     1982枚         1982枚            0枚    99.9%

確認を足すごとに、検出率が段で上がります。落とした確認の分は、そのまま通ります。

面の検査でも同じ形になります。必須の項目、型、値の範囲、余分な項目を、それぞれ確かめるかどうかで通る量が変わります。

記述から自動で確かめる

手で書いた検査は、面が変わると古くなります。記述から生成すれば、面と一緒に更新されます。

確かめる先は2つです。受ける側の応答と、呼ぶ側の要求の両方を、記述と突き合わせます。