API-First設計とは何か？コードの前に契約を設計する

API-First設計とは、実装が書かれる前に、通常はOpenAPIまたはschemaドキュメントとして、APIの契約を規定することを意味します。

API-Firstは通常の順序を逆転させます。サービスを構築してから浮かび上がったendpointを何であれドキュメント化する代わりに、まず契約を設計し、それを信頼できる情報源として扱います。プロバイダーとそのconsumerの両方が、その合意された契約に対して構築するため、並行作業と強力なCI/CDテストの話が解き放たれます。

コードの前に契約

チームは、OpenAPIドキュメントのような機械可読なAPI specを書き、実装の前にそれに合意します。その specは、後付けとしてではなく、あらかじめendpoint、requestとresponseの形、エラーケースを定義します。

それが役立つ理由

frontendとbackendのチームが同じspecに対して並行して構築します。
早期テストのためにspecからmockサーバーを生成できます。
クライアントSDKとサーバーstubをコード生成できます。
契約は、部族的知識ではなくレビュー可能なartifactになります。

pipelineの見返り

specが手元にあれば、pipelineはそれをlintし、実装がそれに適合していることを検証し、consumerに対してコントラクトテストを実行できます。ドキュメント化された契約と実際の振る舞いの間のドリフトは、本番環境での驚きではなくbuildの失敗になります。

互換性を壊す変更を早期に捕捉する

契約はversioningされているため、pipelineは提案されたspecを現在のものとdiffし、リリースされる前に互換性を壊す変更を指摘できます。それは後方互換性を、手動レビューではなく自動化されたチェックに変えます。

どこに適合するか

API-Firstは、多くのconsumerがサービスに依存するとき、チームが並行して作業するとき、または公開APIを公開するときに輝きます。1つの呼び出し元しかない小さな内部ツールでは、初期の儀式は割に合わないかもしれません。

CIでの生成とテスト

コード生成とコントラクト検証は、すべてのbuildにステップを追加し、それらのステップは多くのサービスにわたって絶えず実行されます。速くwarmなrunner（Latchkeyが提供するような）は、追加された検証がフィードバックループを遅くするのを防ぎます。

重要なポイント

API-First設計は、実装コードを書く前に契約を定義します。
単一のspecから並行作業、mocking、コード生成を可能にします。
pipelineは適合性を検証し、互換性を壊す変更を自動的に検出できます。