3
予測される変更を計画しているRESTエンドポイントの推奨パターンは何ですか
変更のための先見の明を持つ外部アプリケーション用のAPIを設計しようとすることは簡単ではありませんが、少し前もって考えておくことで、後で生活が楽になります。私は、以前のバージョンのハンドラーをそのままにしておくことで、後方互換性を維持しながら将来の変更をサポートするスキームを確立しようとしています。 この記事の主な関心事は、特定の製品/会社に対して定義されたすべてのエンドポイントでどのパターンに従う必要があるかです。 基本スキーム のベースURLテンプレートを考えると、https://rest.product.com/すべてのサービスが/api、/authおよびなどの他の非レストベースのエンドポイントと共に存在することを考案しました/doc。したがって、次のようにベースエンドポイントを確立できます。 https://rest.product.com/api/... https://rest.product.com/auth/login https://rest.product.com/auth/logout https://rest.product.com/doc/... サービスエンドポイント 次に、エンドポイント自体について説明します。懸念はPOST、GET、DELETEこの記事の主な目的ではなく、それらのアクション自体に懸念されます。 エンドポイントは、名前空間とアクションに分類できます。また、各アクションは、戻り値の型または必須パラメーターの基本的な変更をサポートする方法で表示される必要があります。 登録されたユーザーがメッセージを送信できる架空のチャットサービスを利用すると、次のエンドポイントがある場合があります。 https://rest.product.com/api/messages/list/{user} https://rest.product.com/api/messages/send 今度は、壊れる可能性のある将来のAPI変更に対するバージョンサポートを追加します。私たちは、どちらかの後にバージョンの署名を追加することができ/api/たりした後/messages/。与えられたsendエンドポイント我々は、v1の以下のものを持つことができます。 https://rest.product.com/api/v1/messages/send https://rest.product.com/api/messages/v1/send だから私の最初の質問は、バージョン識別子の推奨場所は何ですか？ コントローラーコードの管理 そのため、以前のバージョンをサポートする必要があることを確立しました。そのため、時間の経過とともに廃止される可能性のある新しいバージョンのそれぞれのコードを何らかの方法で処理する必要があります。Javaでエンドポイントを記述していると仮定すると、これをパッケージで管理できます。 package com.product.messages.v1; public interface MessageController { void send(); Message[] list(); } これには、すべてのコードがネームスペースを介して分離されているという利点があります。この場合、重大な変更はサービスエンドポイントの新しいコピーを意味します。これの不利な点は、すべてのコードをコピーする必要があり、新しいバージョンと以前のバージョンに適用するバグ修正を各コピーに適用/テストする必要があることです。 別のアプローチは、エンドポイントごとにハンドラーを作成することです。 package com.product.messages; public class MessageServiceImpl { public void send(String version) { getMessageSender(version).send(); } // Assume we have …