經驗分享：eBay的API智慧設計

banq發表於2019-07-26
API

單個API不足以讓開發人員具有創新性。當API一起使用時，API非常強大，因此組合維度才是最重要的.
API允許組織大規模地為其合作伙伴提供對資料和功能的訪問。可擴充套件和適應性強的API生態系統使開發人員更容易進行創新。建立這樣一個生態系統是一個前進的過程，面臨許多技術挑戰。
API代表業務，使其能夠擴充套件到新的上下文和體驗。整個API組合為組織帶來了價值。單個API不足以讓開發人員具有創新性。API一起使用時功能強大，因此組合維度才是最重要的。組合使用讓我們的API可以訪問有價值的eBay市場功能。使用烹飪類比API整合，我們相信我們提供健康的成分。我們的開發人員社群應該發揮創造力，並提出很好的方案來滿足客戶的需求。 

開發生態系統
“正是知識發展最令人滿意的結果之一就是不斷開放新的和更大的前景。” - 尼古拉·特斯拉
最簡單的API方法是設計直觀，直接的合同。API是人們的介面。它們適用於人類開發人員。（人工智慧仍然很重要。）目標是與API整合，而不需要花太多時間在文件上或提交開發人員技術支援票。API就像一個講笑話，如果需要進一步解釋通常表示其已經具有不必要的複雜性。
通常，API做三件簡單的事情。（我將跳過有時落後於以下步驟的所有技術挑戰。）

  • 執行操作並收集資料
  • 格式化資料
  • 提供資料

評估API的價值需要時間; 瞭解釋出API是成功還是失敗。必須接受變革並強調靈活且適應性強的API生態系統。如果你擁有的只是一把錘子，那麼每個問題看起來都像釘子一樣。 當滿足開發人員的需求具有挑戰性時，API所有者應該改變觀點並尋找不同的解決方案來改進API組合。通常，有許多方法可以解決問題。構建開發人員生態系統很困難，有很多技術（和其他）挑戰，但如果做得好，它會朝著正確的方向擴充套件。
在商業世界中，破壞性力量如今是強大的。增強和虛擬現實和人工智慧，語音和影像識別，以及各種自學系統，無處不在。這些創新有能力極大地重塑購買和銷售體驗，並改變人們與數字世界互動的方式。在eBay，我們透過API公開這些功能。去年夏天釋出的影像和機器文字翻譯僅僅是一個開始。
另一方面，有時API功能會因各種原因而消失：業務策略或策略更改，不符合業務目標，難以整合。因此，還需要標準化API生命週期的這一方面。

API棄用版本的標準
在eBay上，我們有API版本控制和棄用的規範。版本控制在開發人員中是一個有爭議的話題。這是API世界中最常見的爭論之一。在處理不正確版本的基於SOAP的API 10年之後，我們決定使用新的現代RESTful API來改變方法。我們遵循語義版本控制並定義了alpha，beta和一般可用性質量級別。此外，我們支援實驗API。這些功能的目的是探索，測試並獲得API早期採用者和合作夥伴的反饋。
我們的API棄用標準主要關注API契約和執行時行為。棄用規範適用於所有API質量級別：alpha，beta和一般可用性以及實驗功能。棄用API版本或整個API是API生命週期的最後階段。當API不符合業務目標時，它是最佳選擇。API棄用的一些原因是：

  • 業務政策或戰略變革
  • 實驗能力/ API不再符合業務目標
  • 無效
  • 使用率低

可以棄用的API元素包括：
  • 資源/方法
  • 領域
  • 列舉值
  • 查詢引數
  • HTTP標頭
  • 行為
  • API（主要）版本
  • 所有主要版本的整個API

不推薦使用的API元素以原始形式保留18個月。此政策的例外情況是可能的，並適用於關鍵業務決策。透明的公告隨附任何API元素的棄用。它包含開發人員的詳細說明，包括遷移計劃（如果適用）。API棄用公告發布在我們的Developer Portal上，可能包含其他通訊渠道。
在某些情況下，不推薦使用的元素會導致向後不相容的更改。由API產品所有者決定方法：繼續棄用或釋出新的主要版本。
我們使用OpenAPI規範中的deprecated屬性來宣告不推薦使用的API元素：方法，欄位，查詢引數和標頭。此外，我們更改OpenAPI規範描述屬性以反映棄用。以下示例適用於棄用的actualDeliveryDate欄位。 

ShippingFulfillment:

 type: "object"

 properties:

   actualDeliveryDate:

     type: "string"

     description: "This field has been deprecated. For instructions on how to migrate to the new version, visit eBay Developer Portal. The date the purchase order was delivered."

     deprecated: true


對於任何新棄用的API元素，我們會釋出一個新的次要API版本。此類版本需要API文件更新，它包括新的API合同以及與開發人員的正確通訊。

HTTP響應標頭以傳達棄用
在執行時，我們利用標準的警告 HTTP響應頭和  299程式碼來反映不推薦使用的API元素。開發人員將記錄和監視Warning標頭的用途。根據HTTP協議規範，299程式碼（雜項持久警告）不是用於棄用的專用程式碼。為了簡化客戶端上此資訊的使用，我們僅對已棄用的API元素使用299程式碼。在任何API棄用的情況下，無論HTTP狀態程式碼如何，警告 HTTP標頭都存在於每個適用的響應中。
當一個方法，查詢引數或HTTP標頭不推薦使用時，這些響應中帶有警告Warning標頭，作為響應一部分。
對於欄位、列舉值或行為不推薦使用時，來自使用這些元素或相關元素的所有方法的響應都指定了  警告Warning標頭。
API​​主要版本不推薦使用時，每個方法的響應都包含一個  Warning標頭。如果整個API棄用，這適用於所有API主要版本。
API客戶端應記錄HTTP棄用標頭並具有適當的警報和監控。eBay開發者入口網站上記錄了說明和示例，作為與eBay RESTful公共API整合的最佳實踐的一部分  。

句法
Warning: <warn-code> <warn-agent> <warn-text> [<warn-date>]

<warn-code>
一個三位數的警告號碼。始終為299（雜項持久警告）以反映已棄用的API元素。這裡的299程式碼不是HTTP響應狀態程式碼; 它只是警告標題內容的一部分。

<warn-agent>
warn-agent值是API主機名。示例：api.ebay.com，api.sandbox.ebay.com

<warn-text>
警告頭包含的警告文字，其中包含有關棄用的簡要資訊。警告文字有一個指向公共API文件的連結，用於解釋棄用。警告文字旨在呈現給人類使用者或記錄。

<warn-date>
包括棄用日期。格式與RFC 7231日期/時間格式定義的HTTP Date標頭相同。

候選欄位
可以生成多個警告，具有相同的299程式碼和不同的警告文字作為響應。這是為了反映在不同時間點棄用的多個API元素。

例子
在Account API中不推薦使用返回策略欄位restockingFee和extendedHolidayReturnsOffered。下面警告 HTTP標頭是存在於用於RETURN_POLICY資源定義的所有方法。

Warning: 299 api.ebay.com "Deprecated return policy fields: restockingFee and extendedHolidayReturnsOffered. We will keep supporting them for the next 18 months. For more information, visit https://developer.ebay.com/api-docs/sell/account/deprecation.html" “Wed, 15 Jun 2018 00:00:00 GMT”


不推薦使用Account API的第1版時，低於Account API版本1下的所有方法HTTP標頭出現警告。

Warning: 299 api.ebay.com "You are using a deprecated version of the API. We will keep supporting it for the next 18 months. For instructions on how to migrate to the new version, visit https://developer.ebay.com/api-docs/sell/account/deprecation.html" “Wed, 15 Jun 2018 00:00:00 GMT”


我們考慮使用標準的Sunset HTTP標頭向客戶傳達API棄用的事實，但由於以下原因而放棄了這個想法：
  • 在Sunset 響應頭仍處於草案。
  • 在Sunset 響應頭指示資源或API即將退休。它不適合棄用其他API元素：欄位，列舉值和行為。
  • 不支援多個Sunset標頭來傳達在不同時間發生的多個棄用。當資源預期無響應時，Sunset響應標頭包含單個時間戳。 

我們還在跟蹤今年努力引入（和標準化）  Deprecation HTTP響應標頭，以向客戶發出API棄用訊號。

軟體開發工具包
“我們就是要反覆做。那麼，卓越不是一種行為，而是一種習慣。“ - 亞里士多德
API是使應用程式能夠互動的中介。它們是開發人員創新和創造產品的基石。另一方面，SDK是透過抽象一些概念（例如各種橫切關注點）來簡化構建塊的工作的工具。SDK使開發人員能夠建立新的應用程式或新的構建塊。
今年，我們繼續使用API​​的開源工具。我們最近釋出了C＃和Python OAuth客戶端庫，可以簡化與API的整合。這是以前開源的Java OAuth客戶端庫的補充。為了獲得適當的授權並解決資料隱私問題，我們利用行業標準的OAuth 2.0協議。所有eBay API都要求客戶獲得使用我們的市場功能的授權。利用我們的庫時，只需幾行程式碼即可與eBay OAuth服務整合。
Feed API向我們的合作伙伴公開了最多的庫存選擇。這包括新的日常用品以及稀有商品  - 如果世界上存在某種東西，最有可能在eBay上出售。合作伙伴使用我們的資料Feed建立豐富的專案選擇，並使使用者能夠找到完美的版本。Feed SDK抽象下載和大檔案操作，簡化了典型的複雜庫存管理。它們允許全球的授權合作伙伴以程式設計方式訪問大量的eBay專案，並根據他們的商業模式策劃他們選擇的庫存。在去年的Java Feed SDK之後，我們最近釋出了Python客戶端。
在去年夏天的eBay Connect上，我們宣佈OpenAPI文件可用於我們的RESTful API。我們證明了與只讀功能的整合需要幾分鐘時間。我們的庫可以進一步簡化。我們開源的SDK不是提供黑盒子，而是為開發人員提供完全透明的整合功能。（我們歡迎開發者社群的貢獻！）
 

相關文章