《TO》導讀：Amazon 最近的新聞不斷，我們曾分享過《亞馬遜 CEO 貝佐斯決定退休了，誰是接班人？》、《亞馬遜舉白旗 CEO 貝佐斯：在中國，我敵不過淘寶網》等。
而今天我們要討論的是 Amazon 的 API 問題。
本文作者為 Sean Clark。他是 ConnectAI.com 與 Whitebox.co. 的共同創辦人，同時也是資深工程師。Clark 在深入研究各種備受愛戴的 API 後，他確切點出 Amazon 在 API 所犯下的錯誤，並解釋 API 到底要怎麼寫才對。
現在，就讓我們來看看他的論點吧；本文以第一人稱敘述。
Amazon 到底錯在哪裡？
今年一整年，我深入研究了許多相當受歡迎的 API（應用程式界面），其中包含了 Facebook、eBay、Twitter、Stripe、Papal、Quickbooks 與 Amazon。
大部份的 API 都使用一個常見的模式，REST（Representational State Transfer） 或是基於 API 核心的 NVP（Name Value Pair）。通常也都提供數種方式來處理需求認證；接著，會有一種以上的方法來發送各種資料格式，例如 JSON、XML 或 file stream。
但有個情況總是讓我感到困擾。這些核心 API 的文件通常缺東漏西的，但他們開發了幾種特定語言的 SDK。表面上看起來很合理，你可以自己選擇語言來輕鬆的使用我們的 API；但其實這個想法是有瑕疵的。
你使用 API 的方式跟我不同，而且你不會去更新 API 讓它符合當下的流行／改變。
- SDK（軟體開發套件）VS. API（應用程式界面）
我向大家舉個例子，來解釋我到底想要表達什麼。
Amazon MWS（Marketplace Web Service，市場網頁服務）是他們的商業服務 API，用以在 Amazon 上排列所販售的商品、更新價格、新增圖片、取得賣家報告等等。Amazon MWS 提供給你 PHP SDK 來實作 API，其中有 11 種不同的 API 下載，每種大約有 124 個檔案，佔據 700kb 的容量，可以從此連結下載 http://bit.ly/1fyXYjn。
聽起來是不是讓人有點頭暈想吐？這個 SDK 就一共有 1364 個檔案，有沒有什麼方式可以讓 API 的使用方式簡單一點？
讓我們跟他們的 API 遊樂場（這真的是個很棒的想法，每個人都應該要擁有）對照一下（遊樂場是一種可以很快的玩每個 API 可以做到的事情的工具）。Amazon 的遊樂場連結在此 http://bit.ly/1iEJVfc；其中有兩個下拉選單，第一個給你九個選項，而第二個是隨著第一個選單而改變的變動式選項。
這個有著兩個下拉式選單的遊樂場可以做所有那些 1364 個檔案能做的事情。
- Amazon 到底想要我們怎麼用它的 API？
我們現在來看看 Amazon 的開發者認為我們該如何使用他們的 API。我們的目標：按照我帳號的訂購紀錄來排序。
這個 API 的案例檔案在 Orders download > src/MarketplaceWebServiceOrders/Samples/ListOrdersSample.php
這個檔案有 114 行、4,447 個字元。你首先需要了解，他們包含了一個必須先編輯的設定檔（config file）。
注意：他們使用在設定檔裡的文字與正確的文字並不對等。他們也不告訴你要去哪裡拿這些 API 鑰匙。
提示：你得提供 AWS 憑證。
接著，我們會有另外兩個設定區塊（config block），現在你所看到的是我最喜歡的行數之一。
$request = new MarketplaceWebServiceOrders_Model_ListOrdersRequest();
真是太漂亮了。這可是我見過史上最長的名稱。
接著他們設定更多的資訊，借助於此頁面的一個功能，然後最終顯示結果的 XML 檔案。當然這些資料對 PHP 是沒用的，你還是得解析 XML（沒有在他們的範例中顯示過）。不過，這不就是 SDK 的用途嗎？
我將快速講解你們該如何使用這個程式。步驟如下：
1. json_decode(json_encode($xml),true)；得到資料的 PHP 儲存格範圍。
2. 搞清楚你要得到訂單的關鍵是什麼。
3. 了解事實。因為這曾經是 XML，如果只有一筆交易，它不會在索引值是 0 的陣列中，而是一個關聯陣列（Associative array）。
4. 了解 Amazon 每次要求只給你 100 個訂單，所以如果你要求更多訂單，必須用 listOrdersByNextToken 才行。
5. 如果你一次提出太多筆，Amazon 將會阻擋你的要求，所以你需要閱讀那些文件來了解你可以進行幾次呼叫，然後把間隔時間設定進你的程式迴圈中。
6. 如果你需要做其他的 API 開啟，像是 listOrderItems，你需要小心處理他們的阻擋行為。
7. 如果你到現在都還沒放棄，那可能你真的賺很多。
我不相信 Amazon 會多期望我用他們的 API。我寧願使用 API 遊樂場，然後只要 2 個下拉選單就可以做所有的工作。
而 Amazon 並不是唯一一個犯這種錯的人。
解決方式看起來十分簡單。雖然一開始會需要較高階的編碼，但你會有個很開心的生活。這方法就是，你只要運用簽名檔就可以了。
忘了 SDK 和其他的東西吧，只要想清楚要怎麼用你的語言執行直接的 API 開啟。
$AmazonAPI = new Amazon($config);
$orders = $AmazonAPI->call(“Orders/ListOrders”,[]);
上面兩行可以做到之前那六個步驟的所有事情。此外，你還可以更改開啟的範圍 () 來符合任何 API 遊樂場有的東西。而資料儲存格範圍也會完全符合 API 文件所要求的。
這個功能 $Amazon->call() 可以做那些 11 個下載檔裡的 1346 行代碼可以做到的事。
我做的 Amazon class 有多大？一個檔案、235 行的程式碼還包含註解。
- 真正的 SDK，是該如此做的！
這個部分依照公司而不同。Ebay 要你有特別的 X- 標頭，要你用 sha256（安全雜湊演算法 256）來簽署。Amazon 要你用 sha256 簽一個 URIEnocode 編碼串。Quickbox 則是用 sha1。
為了搞清楚這一切，你首先需要一個工作開放資源版本。如果沒有工作開放資源版，我就無法建立這些 SDK。
基本步驟如下：
1. 在開放資源 SDK 中開啟一個 API，使之運作
2. 找出 cURL 請求是在哪裡做出的
3. 為剛剛做出的請求除錯，以便確認傳出的資訊
4. 找到簽名檔功能並複製
5. 試著自己開啟程式，並開始閱讀錯誤訊息
6. 如果你卡住了，請求開發者支援，讓他們告訴你你錯在哪裡
TO 編按：本文為技術討論文章，發布後感謝忠實讀者 Che 提供很多編譯校訂上的建議，若您也看到這篇文章有錯誤或更好的編譯方式，請您不吝來信 [email protected]，或直接在文章下方留言，我們會儘快修訂。
（資源來源：Medium；圖片來源：Jurgen Appelo，CC Licensed）
