共存できるインターフェースを設計する

一貫性が美しさより先

すべてのルートで同じ命名規則、同じレスポンス構造、同じ日付形式、同じエラー構造。一貫性のある十のルートは、輝く五つと異なる五つより簡単だ。

安定した構造を返す：データとメタデータを持つラッパーオブジェクト、フィールドを壊さずに追加できるように。

戻ってくる決定

ページネーション。事前に決める——オフセットかカーソルか——すべてのリストでサポートする。ページネーションなしのリストは常に期待以上に成長する。

フィルタリングとソート。定義され文書化され、各消費者がルールを発明するフリーフィールドではない。

識別子。安定していて、連番でなく、その数でビジネス情報を明かさない。

エラーはコントラクトの一部

正しいステータスコード、ロジックを分岐できる固定エラー識別子、読めるメッセージ、調査のためのリクエスト識別子。エラーごとに異なる自由テキストを返すインターフェースは、消費者に文字列確認を強制する。