API設計書の書き方｜利用側へ伝える項目と記載例

API設計書は、APIを提供する側と利用する側が、呼び出し方と結果の扱いを共有するための文書です。URLと項目名があっても、必須条件や失敗時の意味が抜けていると、同じ仕様を見て別の実装を作ってしまいます。

この記事では、設計方針を選ぶ段階の後に、決まった約束を利用側が実装・確認できる形へ書く方法を説明します。表計算、Markdown、OpenAPIのどれを使う場合も、読み手の疑問が解消されることが大切です。

操作の目的と利用条件を書く

最初に、操作の名前、用途、呼び出す主体、対象環境を記載します。読み手が「この操作で何ができ、何はできないか」を判断できるようにします。

たとえば「申請取得API」だけでなく、「指定IDの申請を参照する。ログイン利用者に閲覧権限がある場合に限る」と目的と条件を分けて書きます。これは説明用の仮仕様です。

認証方式の説明には、利用に必要な設定や権限の参照先を添えます。実際のトークンやパスワードは設計書へ貼り付けません。

同じ「id」でも、URLの一部なのか、問い合わせパラメーターなのか、本文なのかで呼び出し方が変わります。OpenAPIの公式説明でも、パラメーターの場所や、リクエスト本文を区別しています。OpenAPIのパラメーターとペイロード

次の表は、架空の申請参照APIの記載例です。

一覧検索なら、未指定時の値、上限、空文字の扱いなども必要に応じて加えます。「任意」とだけ書かず、省略した場合に何が起きるかを説明してください。

OpenAPIでは、パスごとの操作に、パラメーターや応答を記述します。応答コードに加えて、その操作での意味を説明する構造です。OpenAPIのAPI Endpoints

設計書でも、成功時だけでなく、利用側の行動が変わる失敗を記録します。

応答例は、項目表と一致する架空データで作ります。日時のタイムゾーンや金額の単位も書いてください。例にしか出てこない項目や、仕様と違う型が残っていないかを確認します。

OpenAPIなどの構造化形式は、操作や入出力の形を共有する手段になります。ただし、ファイルが構文上正しいだけで、業務上の仕様が正しいとは限りません。

たとえば「申請確定後は変更できない」という業務条件は、どの状態でどの操作を許すかまで説明が必要です。同時更新、重複送信、タイムアウト後の確認など、複数の操作にまたがる条件は補足文書やシナリオで示す方法があります。

資料が分かれる場合は、どちらが正本かを決めます。項目表だけ更新してサンプルが古いままにならないよう、関連する版を対応づけてください。

レビューでは「読めたか」ではなく、「これだけで呼び出しと結果判定を実装できるか」を確かめます。説明のない前提が出てきたら、その場だけで伝えず文書へ戻します。

変更時には、変更項目、適用する版、利用側の対応要否を残します。テスト項目との対応は受入テストの準備も参考になります。

最初は重要なAPIを一つ選び、入力・応答・失敗・利用条件を埋めてください。開発の体制づくりは、システムエンジニアリングサービスをご覧いただけます。