一般的に、RESTサービス用のクライアントライブラリを開発して、APIの破損を防ぐ必要がありますか?


9

UIコードが同じチームによって開発されるが、サービスレイヤー(REST / Java)とは異なる言語(Python / Django)で開発されるプロジェクトがあります。各レイヤーのコードは、異なるコードリポジトリに存在し、異なるリリースサイクルに従うことができます。UIレイヤーの観点から、サービスレイヤーの重大な変更を防止/軽減するプロセスを考え出そうとしています。

UIまたはサービスレイヤー(2つのGitリポジトリにあるコードをビルドするためのCIツールとしてJenkinsを使用しています)を構築するたびに実行するUIレイヤーレベルで統合テストを作成することを考えました。障害が発生すると、サービスレイヤーで何かが壊れ、コミットが受け入れられません。

また、サービスレイヤーの開発者に、UIレイヤーに存在するRESTサービスのクライアントライブラリを作成および保守してもらい、UIレイヤーに重大な変更があった場合に更新するようにしてもよいでしょうか(ベストプラクティスですか?)。彼らのサービスAPI?おそらく、UIコードが構築する静的に型付けされたAPIの利点があるでしょう。クライアントライブラリAPIが変更された場合、UIコードはコンパイルされません(したがって、重大な変更があったことがすぐにわかります)。また、UIまたはサービスレイヤーの構築時に統合テストを実行して、UIとサービス間の統合が引き続き機能することをさらに検証します。


6
APIが変更されたときに通知されていませんか?このような場合は、APIをバージョン管理するのが最善の場合が多いため、UIは常に機能するバージョンになります。次に、できるだけ早く最後のAPIバージョンに「アップグレード」します。
Matt S

@マット:私はあなたに同意します。しかし、通信の有無にかかわらず:変更されたAPIへのアップグレードは、コード内で変更する必要のあるすべての場所をコンパイラーが正確に指示すると、はるかに簡単になります。OPはまだ彼のPythonコードが静的に型付けされたAPIを提供する方法を教えてくれませんが。
Doc Brown、

回答:


1

一般に、廃止されるAPIのメソッドについては、特に完全な代替APIが利用可能になり、テストされるとすぐに、規則を選択してそれらを「非推奨」にします。(本質的に)古いAPIはそのままにしますが、メソッドシグネチャメタデータにタグを付けるか、ログイベントを挿入して、使用状況を明確に識別できるようにします。

サービスAPI内でのロギングは1つですが、消費しているクライアントへのアラートはもう1つです。RESTについては、しっかりとした標準的なプラクティスがあるとは思いません。FourSquare APIクライアントは、呼び出されたメソッドが成功した場合でも、廃止されたメソッドを検出できます(HTTP 200コードですが、errorTypeは '廃止予定'に設定されます)。API内の廃止されたメソッドの知識を損なうことなく知る機会を消費クライアントに提供するためのおそらく妥当な戦略。

https://developer.foursquare.com/overview/responses

APIガイダンスの中で、廃止されたAPIが完全に削除される日付またはビルドリリース番号を提案します。廃止予定の戦略を具体化する際に、APIの利用者に提案された戦略が何であるかを警告する必要があります(廃止予定のメソッドをどのように発見できるか、代替APIに移行する方法、および廃止予定のAPIがいつ利用できなくなるかAPIのクリーンアップ中に削除され、プロセスが全員にとって有益になるように、それらからのフィードバックを求めます。


1

APIのバージョン管理も可能です。新しいバージョンがデプロイされたら、古いバージョンもアクティブのままにして、リクエストによるネゴシエーションを許可します。最新の2または3バージョンを維持している場合、UIコードは独自のペースでアップグレードできます。


1

一度に3つ以上の質問がありますので、一つずつやっていきましょう

  • 「RESTサービス用のクライアントライブラリを用意するのは良い考えですか?」

すべてのUIコードに直接散在する任意のREST呼び出しを望まない限り、おそらくはい。

  • 「サービスレイヤーの開発者にライブラリを作成および維持させることは良い考えですか?」

それはあなたのチームの人々に依存します。APIのメンテナーは、サービスレイヤーで利用可能なものとUIレイヤーの要件の両方を知っている必要があります。したがって、サービスレイヤーのユーザーか、UIレイヤーのユーザーか、(サイズや他のタスクに応じて)両方のチームから独立した人物のいずれかになります。

  • [次の点からメリットがあります]「クライアントライブラリAPIが変更された場合、UIコードはコンパイルされません」

UIはPythonで書かれると言っていませんか?それは静的に型付けされた言語ではないので、APIの変更からすぐにビルドが中断することはないと思います。この時点で間違っていると思いますが、ここに静的に型指定されたAPIがあります。APIに新しい機能(新しいオプションのパラメーターなど)追加するだけでビルドが中断しない限り、ここにいくつかの利点があります。そうしないと、チームに多くの不必要なオーバーヘッドが生じます。

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.