在使用未能正確版本化的SOAP API多年之後，eBay決定轉向新的RESTful API，其中包含語義版本控制和棄用標準。他們的重點放在了可擴展性和適應性上，目標是使開發人員更容易創建使用eBay API的新應用程序。在一篇博客文章中，Tanya Vlahovic描述了這些概念以及它們在API中是如何實現的。
在eBay的首席公共API架構師Vlahovic看來，API代表業務，但她強調，單獨的API是不夠的；它們必須一起使用才能給企業帶來真正的價值。她將eBays的API集與烹飪進行了比較——API是佐料，然後由開發人員社區以一些新的、創新的方式組合不同的API來提供一頓大餐。
要創建一個靈活和適應性強的API生態系統，重要的是要了解單個API是成功還是失敗；它們是被開發人員使用還是被忽略？Vlahovic認爲，API所有者應該非常開放，當試圖改進API並使其得到使用時，應該從不同的角度尋找解決方案。她舉了兩個新API的例子，她認爲它們改變了人們的思維方式，它們就是去年夏天發佈的圖像搜索和機器文本翻譯。
Vlahovic將API描述爲做三件簡單的事情：執行操作和收集數據，格式化數據，最後提供數據服務。她認爲，創建API最簡單的方法是設計直觀、簡單的契約，而不需要花費大量時間編寫文檔，然後讓開發人員試用並評估它的價值。她指出，API是面向人類開發人員的接口，而不是面向機器人的。
在新的RESTful API中，它們遵循三個質量級別的語義版本控制：Alpha、Beta和正式可用。除了這些級別之外，它們還支持實驗性API。這允許早期採用者探索、測試API，並快速反饋。
他們的棄用標準同時關注契約和運行時行爲，並使用了和版本控制中相同的質量級別。當它們廢棄API中的某個元素時，例如資源、字段或行爲，這些元素通常以原始形式維護18個月。對於每一個新棄用的元素，都會新發佈一個API的次要版本，並伴有一個公開聲明，其中包含針對開發人員的詳細說明。如果需要，這些說明中還會包括遷移說明。如果棄用導致向後不兼容，API所有者必須決定是否發佈一個新的主版本，而不是一個次要版本。
無論何時棄用一個元素，都會將deprecated屬性添加到元素中，並更新description屬性以反映該棄用。這兩個屬性在OpenAPI規範中都有定義。在運行時，它們會使用包含299代碼的標準Warning HTTP響應頭來發送棄用通知。這個頭應該被消費者應用程序記錄和監視，以便開發人員可以得到關於新更改的警告。
Vlahovic將API視爲使開發人員能夠創建新應用程序的構建塊。爲了簡化這項工作，eBay提供了SDK，抽象了一些概念。一個例子是行業標準OAuth 2.0協議，eBay使用該協議處理授權和數據隱私問題。它們要求所有API客戶端在使用其市場功能之前都要經過授權，因此，SDK中包含了對這一點的支持。除了現有的開源Java OAuth客戶端庫之外，他們最近還發布了一個C#和一個Python版本的庫。
在早些時候的一篇博文中，Vlahovic寫了eBay兩年的歷程，他們向市場交付了一系列新的API，以及他們在那段時間中學到了什麼。
原文鏈接：