バージョニング

/v1 では追加のみ。その約束が何を含み、破壊的変更がどんな形になるか。

約束

最初の外部キーの発行以降、/v1 の形は増えるだけです。フィールドが削除や改名されることはなく、型が狭まることも、enum が値を失うこともありません。削除や改名は /v2 です。

予告なく変わりうるもの

• どのオブジェクトでも新しいフィールド。知らないフィールドは無視してください。
• 開いた enum の新しい値。relations[].kind は仕様にそう書かれています。今日は synonym と antonym で、他の種類が続くことがあります。
• 新しいエラーコード。ステータスによる汎用的な文言にフォールバックしてください。
• 新しい操作や新しい任意パラメータ。
• データそのもの。エントリーは更新され、例文は書き直され、ランクは再計算されます。updated_at が動きます。

変わらないもの

• 必須フィールドがなくなる、または nullable になること。
• パラメータの意味が変わること。
• パスが変わること。

廃止

/v2 ができても、/v1 は告知から 12 か月間は応答し続けます。告知は変更履歴と、有効なキーを持つすべてのアカウントへのメールで行います。

契約

v1 の OpenAPI 仕様が契約です。これらのページのすべての例はサイトのビルド時に仕様のスキーマと照合されます。ここに書かれているものがサーバーの振る舞いです。