私はAPIの設計に受け取る最も一般的な質問の一つは、どのようにAPIのバージョン管理です。すべてではないが、全く同じAPIですが、私は、ほとんどのチームに適用パターンと実践の一部をAPIのバージョン管理を見つけたものの。私はこれらのコンテンツを収集し、次のバージョン管理戦略に関するいくつかのアドバイスを提供します、戦略は、それらは、API、または外部API内側に配備されているかどうか、APIプロバイダの大半を助けます。
あなたに本当に重要なAPIのバージョン？
APIを使うと、APIの利用者の間で確立されたリンクです。通常の状況下では、あなたがたとの間の結合が簡単に壊れません。URIパターンは、リンクペイロード構造、フィールド、およびパラメータ名、予想される動作、およびその他のコンテンツが含まれています。このアプローチの最大の利点は明白です：APIは、アプリケーションのユーザーの理解を変更しない持続的かつ効果的な確保することができます。
ただし、永続的な変更は非現実的です。時々、ビジネスの変化するので、あなたは、APIに大きな変更を実施する必要があるかもしれません。この場合、最良の方法は、あなたがそのAPIは、コードを修正するためにユーザーをリードすることを確認するために何もしないだろうということです。
途切れない変化に速報
多くの場合、「添加物」のような非破壊の変化は、通常、リソース文に新しいフィールドまたはネストされたリソースを追加し、そして、そのようなPUTやPATCHなどの新しいエンドポイントを、追加のいずれか。クライアントコードを構築するために最初からAPIの利用者は、これらの非破壊変化に適応することができるはずです。
画期的な変更が含まれます：
1. [名前]フィールドまたはリソースのパス、通常、リリース後にAPIの命名規則を統一します。
2.次のように適応する一般的に、ペイロードの構造を変更します。
。フィールドの名前を変更または削除
B。（このアカウントの電子メールアドレスのリストに対処するための1つの電子メールアカウントから移動など）単一の値対多の関係からフィールドを変更します。
C。、APIのURLを変更する状況に至った一貫性のない結果を返します。
あなたが一般に公開APIを離すと一言で言えば、あなたは利用できる、それを維持する必要があり、ユーザーには影響しません。あなたが複数の項目を経験している場合は、既存のAPIユーザーへの損傷を防ぐために、APIのバージョン管理を必要とします。
定義されたAPIのバージョンポリシー
任意のAPI進化するニーズAPIのバージョン管理戦略。あなたのAPIのAPIバージョンは、ユーザーの期待に応じて適応し、異なるバージョンに切り替えることができます異なることになります。私は通常、全体的な管理システムAPIの一部として、次のAPIバージョン管理戦略をお勧めします。
1.あなたは、消費者からのフィードバックを得るために、APIの初期のテストバージョンである場合は、あなたのAPIを作成し、適切に変更が発生することが予想されることがあります。あなたのAPIのデザインも変更される可能性があるため、この段階では、あなたは、いくつかの時間のために、このバージョンを維持します。彼らは変更することを期待する必要がありますので、消費者としては、APIは、発生する可能性が不安定です。
新しいバージョンが存在しない場合2.一度公開し、あなたのAPIは、契約として扱われるべきである、あなたは交換することはできません。
3.継続的な変更は、クライアントが自動的に任意の負の副作用なしに、最新バージョンに移行されます、マイナーバージョンとの問題を引き起こす可能性があります。
4.画期的な変更は、それが一つ以上の主な変更点が含まれているため、顧客は、この新しいバージョンに移行しなければならないことを意味します。あなたは、APIの利用者に適切なスケジュール定期的な通信を確立するために、彼らは簡単に新しいバージョンに移行できることを確認する必要があります。しかし、いくつかのケースでは、これはすぐに達成されないことがあり、そうあなたのチームは、一時的にAPIの以前のバージョンをサポートするように求められます。
APIのバージョンを実装する必要がある場合
APIの新バージョンを必要としたら、我々はそれを処理する方法を知っておく必要があります。APIのバージョンは、3つの一般的な方法があります実現しています。
1.リソースバージョン管理
GET /顧客に送信されたアプリケーション/ vnd.github.v3 + JSON：このバージョンは、例えば、受け入れHTTPリクエストのヘッダを受け入れる部分です。同じURIを維持しながら、リソースのバージョンが必要とするので、これは、アカウントにバージョン管理の好適な形態の数をとります。いくつかのAPIを提供して何のAcceptヘッダーには、最新バージョンのデフォルトのバージョンとして選択しないだろう場合。
2.URIのバージョン管理
このバージョンは、接頭辞や接尾辞、例えば、/ V1 /顧客または/顧客/ V1として、URIの一部です。その正確なコンテンツベースのURIのバージョン管理バージョン管理ほど良くはないが、それはカスタムヘッダーツールをサポートしないように適用されることは、多くの場合、最も一般的です。欠点は、URIがそれぞれの新しいバージョンで変更資源である、一部の人々は、これが変更されたことのないURIの趣旨に反すると思います。
3.ホスト名、バージョンコントロール
このバージョンでは、例えば、URIの一部の代わりに、ホスト名であるv2.api.myapp.com/customers。ときに...
注意：選択したオプションに関係なく、APIのバージョンはメジャー番号が含まれている必要があります。それは少数（すなわち、/ V1 /顧客、ない/v1.1/customers）を必要としません。
バージョン管理ツールを実装
ツールやテクニックは基本的にAPIのバージョン管理プロセスを実装することができます使用してください。継続的な設計上の決定を向上させるために、市場で優れた技術チームとのAPIエディタは、より短時間でより多くのAPIのバージョンとスイッチを生成することができるようになります。
バージョン管理のためのツールと組み合わせることで、開発プロセスの最も重要な部分です。APIの設計はまた、実際には、グローバルAPIサービス、すでにいくつかの優れたWeb APIの設計ツールで存在することができ、バージョン管理ツールです。
さて、EOLINKER、RAML、闊歩、として彼らの言語をサポートするための優れた編集ツールを提供します。EOLINKERバージョンは、コントラストやフォーカスのヒントをマーク使用して、あなたは明らかにコントラストを切り替えることができます。RAML、闊歩は、バージョン・スイッチを使用して、利便性はそれに若干劣るかもしれません。前者のみが中国をサポートすることです。しかし、後者の二つは英語のみをサポートしています。これらのAPIの編集者は、簡単にそれが簡単に短時間で実行されているバージョンを切り替えるになって、APIのバージョン管理を実装することができます。
EOLINKERの公式ウェブサイトを取り付けますwww.eolinker.com
SWAGGERの公式ウェブサイトを取り付けますswagger.io/
RAMLの公式ウェブサイトを取り付けますraml.org/
最終的な考え
覚えておいてください、APIは、あなたの消費者のハブとリンクされています。古い接続を壊し、新しいバージョンが必要です。選択戦略、計画、計画を伝え、APIのユーザーは、これはバージョン管理の究極の目標です。
参考资料：ジェームス・ハイギンバザム、そしてどのようにあなたのバージョンあなたのAPIですか？
オリジナル住所：dzone.com/articles/wh ...