以下の記事の内容は、以前 API インターフェースに取り組んでいたときにまとめた内容を記録して共有します。
HTTP と HTML の初期には、認識できない要素または要素属性に遭遇したブラウザは、そのタグが存在しないかのように動作するというルールがありました。これにより、HTML クライアント アプリケーション (ブラウザ) の「破壊性」を高めることなく、HTML の機能を迅速に更新することが可能になります。(注:初期の HTTP/HTML 設計についての洞察については、Bert Bos の 2001 年の講演「W3C、XML、および標準化」を参照してください。)
同様の例はすべて、ほとんどのインターネット標準自体の作成の指針となる基本ルールにまで遡ることができます。1980 年に Jon Postel によって提案された「堅牢性原則」 :
「自分の行動においては保守的であり、他者から受け入れることにおいては寛大でありなさい。」
API への長期的な変更を適切に管理するための最初のルールは、重大な変更を運用環境にコミットしないことです。理由は簡単です。API を公開して人々が使い始めると、インターフェースは約束されたものになるからです。そしてその約束を破ると、顧客を失う可能性があります。Amazon の Werner Vogels 氏は次のように述べています。「API は永遠です」。彼は2016 年のブログ投稿で次のように述べています 。
「[Amazon では] API の設計が非常に重要なタスクであることを認識しています。なぜなら、API をうまく設計できるチャンスは 1 回しかないからです。」
API インターフェースの下位互換性に関する 3 つのルール
API エコシステムに破壊的な変更が導入される可能性を減らすために使用できる、いくつかの簡単な実装ルールがあります。API を長期的に適切に管理したい場合は、これらを API 設計の一部にし、実践方法を確認することが重要です。
ルール 1: 何も持ち去らないでください。
最初のルールは、API を公開したら、そこから内容を持ち出すことはできないということです。約束された URL、入力パラメータ、または出力データ ポイントを取り除くことはできません。API の特定の要素が消えるか変更される可能性があることをドキュメントで開発者に伝えたとしても、それはできません。なぜなら、開発者だからです。
この最初の規則の真実は、 「ヒルムの法則」または「暗黙の依存の法則」として知られるもので説明されています。
「十分な数の API ユーザーがいれば、契約で何を約束しても問題ありません。システムの観察可能な動作はすべて誰かによって信頼されることになります。」 - Google の従業員ソフトウェア エンジニア、ハイラム ライト氏。
これは列挙値にも機能します。status というフィールドがあり、そのフィールドに 5 つの可能な値があると記録されている場合、status に 4 つの可能な値しかない場合、後から更新を API に公開することはできません。
ルール 2: いかなる意味も変更しないでください。
2 番目のルールは、API 内の既存の要素の意味を変更できないことを示しています。Promise フィルター ステートメントの count パラメーターが「ユーザー数」を参照している場合、後で同じパラメーターを「ページ数」に変更することはできません。
何かの意味を変えることは、それを取り除いて別のものに置き換えることと同じ効果があります。これは破壊的な変更であり、API に対するヒポクラテスの誓いを放棄することになります。
ルール 3: すべての新機能はオプションです。
3 番目のルールは、新しい機能 (URL、入力パラメータ、出力パラメータ) はオプションであると見なす必要があるということです。元のバージョンで addCustomer オペレーションに 4 つの必須パラメーターを指定した場合、新しい 5 番目の必須パラメーターを追加することはできません。繰り返しますが、これは基本的に古い addCustomer メソッドを削除し、下位互換性のないバージョンの addCustomer に置き換えます。
もちろん、破壊的変更を導入せざるを得ない状況もあります。おそらく、チームが失敗して API が個人を特定できる情報を公開したか、一部の規制が変更されてデータの受け入れや共有が許可されなくなった、などの可能性があります。これが起こったら、枝毛を取り除く時期です。なぜなら、API の新しい「バージョン」は実際には (ソフトウェア用語で) 致命的なフォークにすぎないからです。
フォークはソフトウェア エンジニアリングではかなりよく知られた用語です。これは 1980 年代初頭の Usenet を介したオンライン ディスカッションにまで遡り、プロジェクトの幹から分岐を作成することを指します。フォークから分岐したら、トランクにマージして戻ることは期待できないという前提がありました。今日のソフトウェア エンジニアリングではトランク、ブランチ、マージがよく使用されますが、API は時間が経っても「フォークされたまま」になる傾向があり、再びマージされることはほとんどありません。
重大な変更を導入する必要があることがわかっている場合は、API をフォークして新しい URL 空間で公開します。必要に応じて、それを「バージョン」と呼んでください。ただし、あなたはまだジェームズ・ボンドではないので、新しいバージョンをリリースしても古いバージョンを削除できるわけではないことに注意してください。代わりに、しばらくの間、それらを並行して実行する必要があります。これにより、前述した「中指」の状況全体が回避されます。
Side-by-Side API を使用すると、API コンシューマーは、将来のある時点 (ユーザーのタイムラインではなく、自分自身のタイムライン) でアップグレードする準備ができるまで、現在の API バージョンを使い続けることができます。
Salesforce は、楽しみと利益を得るために API をフォークする方法をよく知っている会社です。彼らは、API の新しいバージョンを年に 3 回リリースする習慣があります。2021 年春の API はバージョン 51 です。最後に確認したところ、2014 年春 (別名 v30!) まで遡るすべての以前のバージョンがサポートされていました。はい、Salesforce は 20 の過去のバージョンを並べてサポートしています。
オープンソースの擁護者であるエリック・S・レイモンドは、「フォーク」を悲劇的または高価な出来事と関連付けています。ソフトウェア フォークの作成は通常、解決不可能な分割を示し、多大な労力の重複を意味します。そして、Salesforce モデルで見たように、API の世界でも同じことが当てはまります。
重大な変更のリリースに取り組む場合は、並行リリース、ドキュメント、オンライン サポートなどにも取り組む必要があります。
