如何響應REST API版本不匹配的警告？

我有一個使用Jersey + Grizzly HTTP Server作爲REST服務器的Java項目。我使用的版本策略是在響應中放置頭文件「server-api-version」，並要求客戶端在請求中放置頭文件「accept-api-version」。如何響應REST API版本不匹配的警告？

在此基礎上實施，我想提供的版本檢查的兩個層次：

拒絕請求，如果從請求主要版本「接受-API版本」小於主版本號從服務器的API版本。
如果請求'accept-api-version'的次要版本小於服務器API版本的次要版本，則接受請求但警告客戶端「我們將停止支持您在X個月中使用的REST API版本」。

我通過實現javax.ws.rs.container.ContainerRequestFilter實現了版本檢查1。但是，如何實現版本檢查2，通常會有一個額外的警告，這很容易被客戶注意到呢？

來源

2016-08-18 Lee

對於支票2，這取決於您的客戶在哪裏或如何使用。這也依賴於客戶端代碼是否是你的控制之下

如果你的客戶是

一個Java庫，再加入已過時警告日誌。
一個js庫運行的是瀏覽器，然後控制檯警告/錯誤可能會有所幫助，但大多數這些被忽視。
任何其他語言 - 使用其各自的警告或棄用系統。
如果它是具有UI的企業應用程序，那麼在UI上顯示錯誤消息也會得到正確的關注。對於面向非企業客戶的UI應用程序錯誤，這將無濟於事，因爲普通用戶大多無法做任何事情。

另一個硬盤的方式（這可能不是在面對客戶的情況下，可以接受的）

如果客戶端源代碼在你的控制，那麼你可以開始打破調用舊版本的API之前，你實際上將其刪除從服務器。讓我解釋我的意思。現在

您的客戶端有一個調用函數getData(params: ParamType)，也是你的客戶在客戶端檢查平坦的setter函數爲useDeprecated(value: Boolean)

你getData(params: ParamType)如果客戶端可以調用的API已過時，如果不允許客戶端則拋出錯誤。

interface Client { 

    //Clients extend this interface 

    void useDeprecated(boolean deprecated); 

    default boolean isDeprecated(int serverVersion, int clientVersion) { 
    // you can string for representing versions as well. 
    // complicated logic of deprecation here 
    return result; 
    } 

    boolean isAllowedToUseDeprecated(); 

    default Object getData() { 
    if(isDeprecated(serverVersion, clientVersion)) { 
     if(isAllowedToUseDeprecated()) { 
     return getDataFromServer(); 
     } else { 
     throw new DeprecatedException(expectedVersion, actualVersion, message); 
     } 
    } else { 
     return getDataFromServer(); 
    } 

    } 

    Object getDataFromServer(); //Clients implement this 
}

假設您的當前版本是2.1.1（211 in int），並且您希望棄用先前的版本2.0.0（200）。然後客戶端使用2.0.0將開始獲得DeprecatedException

這有什麼用？

當一個API被棄用時，客戶端將開始獲得DeprecatedException，他們的調用將失敗，但他們可以應用useDeprecated(value: Boolean)來設置標誌並繼續使用棄用的API。這給客戶帶來了貶值的通知，也爲他們提供了短期的緊急緩解措施。

這個硬性方法對於內部團隊來說效果最好，只有當客戶端來源在你的控制之下。

請務必事先通過警告和控制檯消息進行良好的溝通棄用，並通過郵寄等

來源

2016-08-18 01:23:37 faizan

我的客戶有一個MMC插件（用C＃編寫的），這是我們的控制和Python的自動化腳本這是下在QE的控制之下。你給了我一個非常好的例子，當客戶端用舊版本發送REST請求時，我可以在REST響應中拋出一個帶有警告消息的DeprecatedException，然後客戶端可以爲以下REST請求添加一個參數useDeprecated = true，以強制服務器接受其請求。感謝提示。 – Lee

@李：很高興我能幫到你。 :) – faizan

如何響應REST API版本不匹配的警告？

回答

相關問題