# 前提条件

本規約は以下の前提で作成されたものである。

  • 業務システム向けの Web API 提供
    • サードパーティ向けに広く開発する Web API ではなく、限られたクライアントやシステムと連携すること
    • いわゆる、LSUDs(Large Set of Unknown Developers)ではなく、SSKDs(Small Set of Known Developers)を対象とする
  • RESTish な Web API
    • 原理的な REST を必ずしも守る必要はないが、例えば HTTP メソッドは、参照は GET、登録は POST、更新は PUT や PATCH、削除は DELETE で使い分けていたり、Web API の要求が成功すれば 200(OK)、204(No Content)を返し、リソースが無ければ 404(Not Found)、操作に失敗すれば 500 系のエラーを返すといったことを指す
    • 本規約を利用するに当たり必須条件ではないが、定義例などはそれに基づいて記載しているので注意する
  • スキーマファースト
    • OpenAPI Specification の定義ファイルを駆動に、クライアント・サーバサイドのコード生成やモック時の利用に用い、高速な Web API 開発につなげることを前提とする
      • Python における、FastAPI・Django REST Framework のように、アプリケーションコードから OpenAPI document を自動生成する開発手法も存在するが、本規約はこれは想定しない
    • 定義ファイルの完成度はできるかぎり高め、コード生成やドキュメントの価値を高める
      • OAS 定義からコードを生成し、通常は記載した型・項目長・最大~最小・enum・必須定義・正規表現フォーマットでバリデーションを行い、カバーできない部分のバリデーションをアプリケーション固有ロジックとして実装する方針とする。例えば、複数項目間のチェックや DB を確認しないと行えないチェックである
      • ドキュメントとしての価値を高めるため、その API 呼び出しで発生しうる全ての HTTP ステータスコードを記載する
        • API の振る舞いを読み手に伝えるものとして、どのような異常系があるかは有用な場合が多いからである
  • JavaScript/TypeScript、Java、Go のエコシステムがターゲット
    • OpenAPI Specification は広く受け入れられており、コレに対応する様々なツールやフレームワークといったエコシステムがあり、中には定義された設定がうまく認識されない場合がある。本規約では対応していないツールが多い場合、特定の記法を非推奨とすることがあり、同時にその理由も説明する
    • 全ての言語・フレームワーク・ツールの対応状況は調査しきれていないため、利用するプロダクトの対応状況は利用者側で確認をお願いする