kintone API設計の十年 — 後方互換性との戦い
サイボウズの業務アプリプラットフォーム「kintone」は2011年のリリース以来、十数年にわたって同じREST APIを進化させ続けてきました。一度公開したAPIは何万もの顧客の業務を支えており、安易な変更は許されません。本記事では、後方互換性を守りながらAPIを進化させてきた設計思想を整理します。
Cybozu's business app platform "kintone" has continued evolving the same REST API for over ten years since its 2011 release. Once published, an API supports the operations of tens of thousands of customers, and thoughtless changes are not permitted. This article organizes the design philosophy of evolving the API while preserving backward compatibility.
追加は歓迎、削除は最後の手段
APIの後方互換性を守るための基本原則は「既存フィールドを変えない」「新しいフィールドは追加してよい」「削除は最終手段」です。kintoneではレスポンスJSONに新規フィールドを加える際も、既存クライアントが未知のフィールドを無視して動作し続けることを前提に設計しています。
The basic principles of preserving backward compatibility are: "do not change existing fields," "new fields may be added," and "deletion is a last resort." When kintone adds new fields to response JSON, it does so on the premise that existing clients continue operating by ignoring unknown fields.
バージョン戦略
kintoneのAPIはURLパスに明示的な大バージョンを持たせず、一つの安定した契約を長期にわたって維持する方針を採ってきました。これは「v2、v3とバージョンを増やすとクライアント実装が分散し、長期保守が困難になる」という判断です。新機能は新しいエンドポイントの追加や既存エンドポイントへのフィールド追加で対応します。
kintone's API does not carry explicit major versions in the URL path; it has taken the policy of maintaining one stable contract over the long term. This is the judgment that "increasing versions to v2, v3 fragments client implementations and makes long-term maintenance difficult." New features are handled by adding new endpoints or adding fields to existing endpoints.
廃止ライフサイクル
本当に古いAPIを廃止する必要が出た場合でも、一夜にして消すことはありません。最低でも一年以上の周知期間を設けてドキュメントとリリースノートで告知し、管理画面にも警告を出して移行を促します。「公開→非推奨→警告→廃止」という四段階のライフサイクルを明示しているのが特徴です。
Even when truly old APIs need to be deprecated, they are not removed overnight. A notice period of at least one year is set, with announcements in documentation and release notes, and warnings shown in the admin screen to encourage migration. The clearly defined four-stage lifecycle — "public → deprecated → warning → retired" — is a key characteristic.
顧客駆動の拡張モデル
kintoneは標準機能だけで全業界・全業務に対応するのではなく、「プラグイン」と「カスタマイズ」という二つの拡張手段を顧客に提供しています。プラグインは再利用可能なJavaScript/CSSのパッケージ、カスタマイズは個別アプリに書き込むコードです。両者はAPI契約に強く依存しているため、後方互換性を壊すと膨大な既存資産が一斉に壊れます。
Rather than handling every industry and every business operation with standard features alone, kintone provides customers with two extension means — "plugins" and "customize." Plugins are reusable JavaScript/CSS packages, and customize is code written into individual apps. Both depend strongly on the API contract, so breaking backward compatibility breaks a massive existing asset all at once.
スキーマ進化の実例
例えば、文字列フィールドが内部的に「文字列（1行）」と「文字列（複数行）」に分裂した場合でも、API応答では両者を区別する新フィールドを追加し、既存フィールドの意味は変更しません。新規クライアントは新フィールドを読み、古いクライアントは従来フィールドだけで動作し続けます。
For example, even when a string field is internally split into "string (single line)" and "string (multiple lines)," the API response adds a new field that distinguishes the two while leaving the meaning of the existing field unchanged. New clients read the new field; old clients continue to operate with only the conventional field.
互換性テストの自動化
後方互換性を人の注意だけに頼るのは危険です。サイボウズは過去のレスポンスを記録しておき、現バージョンが同じリクエストに対して同じ応答を返すかを継続的に検証する契約テストを整備しています。フィールドの追加は許容されますが、既存フィールドの消失や型変更はテスト失敗として即座に検知されます。
Relying solely on human attention for backward compatibility is risky. Cybozu has set up contract tests that record past responses and continuously verify whether the current version returns the same response to the same request. Field additions are permitted, but disappearances or type changes of existing fields are immediately detected as test failures.
レート制限と公平性
公開APIには必ずレート制限を設けて、特定クライアントが全体性能を圧迫しないようにします。kintoneでは一テナント当たりの毎秒リクエスト数に上限を設け、超えた場合は429 (Too Many Requests)を返します。レート制限の値も公開APIの一部とみなされ、縮小する際は周知期間が必要です。
Public APIs always have rate limits set so that no specific client pressures overall performance. kintone sets an upper limit on per-tenant requests per second and returns 429 (Too Many Requests) when exceeded. Rate limit values themselves are considered part of the public API, and tightening them requires a notice period.
おわりに
十数年にわたってAPIを壊さずに進化させてきた実績は、新規機能を速く出すよりも既存顧客の業務を守ることを優先するという文化そのものです。「追加してよい、変更するな、削除は長い周知を挟め」という原則は古典的ですが、長期運用するプラットフォームには今も有効な指針です。
The track record of evolving the API for over a decade without breaking it is itself a culture that prioritizes protecting existing customers' operations over shipping new features quickly. The principles "additions are welcome, do not change, deletion requires a long notice period" are classical, but they remain valid guidelines for platforms operated over the long term.