API契約 は何をしますか?
契約とは、自分が制御できず修正もできないコードに対する約束です。これこそがAPIの変更を内部リファクタリングと異なるものにしています。間違えた場合の代償は、自分の選ばないタイミングで、誰か他の人が支払うのです。
設計
リソースには名詞で名前を付け、メソッドに動詞を担わせましょう。ものをモデル化し、それを現在表示している画面をモデル化してはいけません。今日のUIに合わせて整形されたペイロードは、次の再設計で間違ったものになります。
何を公開するかは意図的に決めましょう。返すすべてのフィールドは、返し続けなければならないフィールドです。内部ID、行バージョン、実装の詳細は、スキーマを呼び出し元のコードに漏洩させ、そこに固定してしまいます。
呼び出し元がリトライする可能性のある操作はべき等にしましょう。ネットワーク経由で到達可能な操作はすべて該当します。作成や課金を行う操作には冪等性キーを提供し、タイムアウト後のリトライで二重に実行されないようにしましょう。
一貫性のあるエラーモデルを返しましょう。安定した機械可読なコード、人間可読なメッセージ、そしてバリデーションエラーが発生したフィールドを含めます。呼び出し元はコードで分岐するため、コードは契約の一部です。コードを変更することは、形状が変わらなくても破壊的変更です。
すべてのリストは最初のバージョンからページネーションしましょう。すべてを返すエンドポイントは、テーブルが大きくなるまでは動作しますが、最もデータが多い顧客に対しては失敗します。行が同時に挿入される場合は、オフセットよりもカーソルを優先しましょう。
呼び出し元を壊すもの
スキーマ言語が許可するものであっても、以下は破壊的です:
- フィールド、エンドポイント、メソッド、またはenum値の削除または名前変更。
- オプションのリクエストフィールドを必須にすること、またはフィールドが受け入れる値を狭めること。
- 型の変更(整数から文字列、単一値からリストへの変更を含む)。
- 既存フィールドの名前と型を維持しながら意味を変更すること。これは最悪の種類で、重大な失敗はなく、データが静かに間違ってしまいます。
- リクエストに新しい必須フィールドを追加すること。
- 既存の条件に対するエラーコードまたはHTTPステータスの変更。
- デフォルト値の厳格化、またはフィールドが省略された場合の動作の変更。
安全:オプションのリクエストフィールドの追加、レスポンスフィールドの追加、新しいエンドポイントまたはメソッドの追加、enum値の追加(ただしすべてのコンシューマが未知の値をすでに許容している場合に限る—それを想定せずに確認すること)。
protobufでは、フィールドタグを再利用または再割り当てしてはいけません。フィールドを削除するときは、タグと名前を予約してください。再利用されたタグは、古いデータを新しいフィールドにデコードし、静かにデータを破壊します。
契約を安全に変更する
削除する前に追加し、両方を少なくとも1リリースは動作させましょう:
- 古いものと並べて新しいフィールドまたはメソッドを追加する。
- 両方を書き、新しいものを読み、古いものにフォールバックする。
- コンシューマを移行し、それぞれが移行したことを確認する。
- 後のリリースで古いパスを削除する。
リソースの意味が実際に変わる場合にのみバージョン管理を行い、すべての追加で行ってはいけません。変更ごとにバージョンを作ると、維持しなければならない表面積が増大します。
デプロイ順序
生成されたコードとサーバーは別々にデプロイされ、そのギャップに障害が潜んでいます。まず両方の形状を許容する側をロールアウトしましょう。プロデューサーが新しいフィールドを発行する前に、それを受け入れるコンシューマーを。呼び出し元が新しいリクエストを送る前に、それを受け入れるプロデューサーを。
スキーマがゲートウェイ、プロキシ、または生成されたクライアントを通じて共有される場合、パス内のすべてのコンポーネントを再生成および再デプロイする必要があります。サービスに追加されたが、その前のレイヤーには追加されなかったフィールドは、呼び出し元に届く前に消え、サービス自身のテストでは気付かれません。
検証
形状を変更する前に実際のコンシューマを確認しましょう。契約のドキュメントを信頼するのではなく、呼び出し元をgrepしてください。
契約自体をテストしましょう。シリアル化された形状をアサートするテストは、ハンドラーの単体テストでは完全に見逃される偶発的な名前変更を捕捉します。