外部APIを使うとき、仕様書を読み解くのに時間がかかることがあります。逆に自分がAPIを提供する側になると、どう書けば伝わるのかで悩みます。さらに厄介なのが変更で、ある日突然レスポンスの形が変わって動かなくなる、という事故は珍しくありません。API仕様を扱う力は、読む側でも書く側でも効いてきます。この記事では、APIの仕様を読み書きする手順を、OpenAPIの構造理解から仕様の閲覧、スキーマ定義、変更の伝え方まで順番に紹介します。
1. OpenAPIの構造を理解する
API仕様の記述方法として広く使われているのがOpenAPI（旧Swagger）です。YAMLまたはJSONで書かれ、大きく分けて、APIの基本情報を書く info、サーバーのURLを書く servers、各エンドポイントを書く paths、再利用する定義をまとめる components の4つで構成されます。paths の下には、URLごとにメソッド（get、post など）が並び、その中に、リクエストのパラメータ、リクエストボディ、そしてステータスコードごとのレスポンスが定義されます。最初に見るべきは paths で、どのURLにどのメソッドで何を送ると何が返るか、という全体像がここに集約されています。components に切り出された定義は、複数の場所から参照されるため、同じ形のデータが色々な場所で使われていることを示します。この構造さえ掴めば、初見の仕様書でも目的の情報にたどり着けます。
2. 仕様書を実際に読んでみる
OpenAPIのファイルはそのまま読むと階層が深く、目的の情報を探すのが大変です。OpenAPI Viewer にYAMLやJSONを貼り付けると、エンドポイントの一覧、各エンドポイントのパラメータ、リクエスト・レスポンスの形が整理されて表示され、全体像を掴みやすくなります。読むときのコツは、まずエンドポイントの一覧をざっと眺めて、そのAPIが提供している機能の範囲を把握することです。次に、自分が使いたい操作に絞って、必須パラメータ、認証の方式、レスポンスの形を確認します。特に認証は、ヘッダーで渡すのか、クエリで渡すのか、トークンの形式は何か、といった部分でつまずきやすいので、実際にリクエストを送る前に確認しておくと手戻りが減ります。ステータスコードごとのレスポンス定義も、エラー処理を書く際に必要になります。
この手順で使うツール
OpenAPI Viewer
OpenAPI 3.x / Swagger 2.0 仕様をビジュアル表示
3. データの形をスキーマとして定義する
自分でAPIを設計する場合、あるいは受け取ったデータを検証したい場合、JSON Schemaでデータの形を定義します。定義できるのは、各項目の型、必須かどうか、文字列の長さや数値の範囲、列挙値、入れ子構造、配列の要素の形などです。JSON Schema Validator を使うと、書いたスキーマと実際のJSONを突き合わせて、どこが仕様に合っていないかを確認できます。設計時に有効なのが、まず実際に返したいJSONを1件書き、それに合わせてスキーマを起こす方法です。抽象的に考えるより早く、漏れも少なくなります。注意点として、必須項目を増やすのは既存の利用者にとって影響が大きいため、最初から必須にすべきものを慎重に選びます。「あとで足せばいい」と考えて任意にしておくと、結局データが揃わないという別の問題も起きるので、バランスの判断が必要です。
この手順で使うツール
JSON Schema Validator
JSON と JSON Schema を並べてリアルタイムバリデーション
4. 破壊的変更を見分ける
APIの変更で最も重要なのが、利用者を壊す変更かどうかの判断です。壊す変更（破壊的変更）の代表例は、項目名を変える、項目を削除する、型を変える、必須パラメータを追加する、ステータスコードの意味を変える、エラーレスポンスの形を変える、といったものです。一方、壊さない変更は、任意の項目を追加する、任意のパラメータを追加する、新しいエンドポイントを追加する、といったものです。判断の基準は「既存の利用者が何も変更せずに動き続けるか」です。ここで注意したいのが、レスポンスへの項目追加は原則安全ですが、利用者側が厳密なスキーマ検証をしている場合は壊れることがある点です。提供する側は、追加を許容する設計を推奨として伝え、利用する側は、知らない項目が来ても無視する実装にしておくと、双方が安全になります。
5. 変更を安全に伝える
破壊的変更が避けられない場合は、伝え方と移行期間の設計が必要です。一般的なのがバージョニングで、URLにバージョンを含める方法（/v1/、/v2/）が最も分かりやすく広く使われます。新旧を一定期間並行して提供し、利用者が移行する猶予を作ります。あわせて、いつ旧バージョンを停止するかを事前に告知します。小さな変更であれば、まず新しい項目を追加して両方返す期間を設け、利用者が切り替えた後で古い項目を削除する、という段階的な方法も有効です。ドキュメント側では、変更履歴を残し、何がいつ変わったかを追えるようにします。そして忘れがちですが、非推奨になった項目には、その旨と代替手段を明記しておくと、利用者が自力で移行できます。API仕様は「一度書いて終わり」ではなく、変更を含めて運用するものだと捉えると、設計の判断がしやすくなります。
まとめ
API仕様の読み書きは「OpenAPIの構造を掴む → 仕様を整理して読む → スキーマで形を定義する → 破壊的変更かを見分ける → バージョニングと告知で安全に移行する」という流れで進めると、読む側でも書く側でも迷いが減ります。特に「既存の利用者が何もせずに動き続けるか」という破壊的変更の判断基準は、設計のあらゆる場面で使えるので覚えておく価値があります。