了解基於 API 的平台：產品經理指南

今天構建數字產品是將無數的各種後台系統與客戶接觸點和設備集成在一起。 聘請軟件團隊將它們連接到一個工作解決方案中的成本可能會飆升。

這就是為什麼現代產品經理在選擇供應商時通常將集成能力放在首位，這可能歸結為選擇暴露 API 的系統。 API 是什麼以及如何在不讓您的技術團隊參與的情況下對其進行測試？ 繼續閱讀。

擁抱數據：為什麼我們需要 API

客戶數據改變了企業的運作方式。 如果正確收集和轉移，它們可以幫助公司提高客戶獲取和保留率，最終導致收入激增。

但是數據處理是一項乏味的工作。 這就是商業利用計算機科學的原因。 在 1990 年代，自動化最耗時的數據任務的數據庫在營銷部門中大受歡迎。 這導致了營銷策略構思方式的巨大轉變——這種轉變被稱為數據驅動方法。

不過，數據庫有一個主要缺點。 為了使它們有價值，公司需要聘請軟件工程師。 他們是知道如何將大量數據轉化為有效見解的英雄。 他們也是保護數據完整性的衛士，從而確保系統面向未來。

但是軟件工程師的成本很高，而且他們的通信接口需要付出努力。

當數據收集渠道的數量跨越多個部門甚至外部公司時，數據庫及其運營商就成為了瓶頸。 企業需要找到一種訪問數據存儲的自動化方式。

這就是 API 優先系統的想法的起源。

沒有技術術語的 API 實際上是什麼

API 優先系統，今天通常簡稱為 API（應用程序可編程接口） ，是確保其他系統可以以統一和安全的方式訪問其數據的應用程序。

沒有計算機科學等級，應用程序可編程接口並沒有真正敲響警鐘。 讓我們看一個更具體的解釋。

到目前為止，我在網上找到的最好的類比之一是 Taija 寫的：

“如果你作為顧客去餐廳，你是不允許進入廚房的。 你需要知道什麼是可用的。 為此，您有菜單。 查看菜單後，您向服務員點菜，服務員將其傳遞給廚房，然後由服務員提供您要的東西。 服務員只能提供廚房能提供的東西。

我見過的最好的 API 類比：拿一家餐館。 菜單是 API，您的訂單是 API 調用，廚房的食物是響應。

— Aarthi 發財！ (@AarthiD) 19. 2013 年 12 月

這與 API 有什麼關係？ 服務員是 API。 你是一個尋求服務的人。 換句話說，您是 API 客戶或消費者。 菜單是解釋您可以從 API 中請求什麼的文檔。 例如，廚房是服務器； 一個只包含特定類型數據的數據庫——無論買家為餐廳購買了什麼作為食材，廚師決定他們將提供什麼，以及廚師知道如何準備什麼。”

再說一遍：

• 廚房
  數據庫，不允許客戶保護數據完整性。
• 服務員
  API，一個知道如何在不中斷其功能的情況下從數據庫提供數據的中間人。
• 顧客
  想要獲取數據的外部系統
• 菜單
  數據格式參考外部系統必須使用來執行它們的操作。
• 命令
  實際的單個 API 調用。

以目前的技術狀態，仍然需要軟件開發人員“下訂單”。 但它的速度更快（閱讀：更便宜），因為菜單，就像麥當勞一樣，在世界範圍內或多或少是標準化的。

所以現在，我們將穿上軟件開發者的鞋子，嘗試調用一個示例 API。 別擔心； 我們不會超越學校的計算機科學課程。

您的天氣應用程序如何獲取數據：API 基礎

我們將了解您的天氣應用程序如何知道當前溫度。 通過這種方式，我們將了解如何通過 Internet 與系統通信的基礎知識。

我們需要的：

• 天氣數據庫
• 瀏覽器
• 一點意志力

而已！ 當今的技術使測試 API 變得容易，而無需大型開發人員工具。

當然，當您想要創建一個完整的集成時，情況就不同了。 緊要關頭，您需要了解更高級的工具和編程語言，但對於測試/概念驗證，這種設置就足夠了。

因此，讓我們嘗試獲取您所在城市的當前溫度指數——或者，用編碼人員的話來說——讓我們調用第一個 API 調用。 畢竟，它歸結為向服務器發送一些文本並接收消息作為交換。

API 請求剖析

在本文中，我們將使用 https://openweathermap.org API。 訪問該站點並嘗試檢查多個位置的天氣狀況。 希望你今天在卡托維茲感覺比我好：

正如您可能已經猜到的那樣，該網站正在調用 API 來獲取數據。 開發人員以每次按下搜索的方式實現它，應用程序在後台敲開 API 的門並說“給我 <city> 溫度”。

讓我們戴上黑客的帽子，看看這個網站用你的瀏覽器調用的 API 調用。 您可以在瀏覽器中使用開發者工具來查看幕後發生的事情：

1. 在 Chrome 中，轉到菜單 → 更多工具 → 開發者工具；
2. 切換到網絡選項卡；
3. 嘗試在上面的小部件中檢查不同城市的溫度；
4. 在底部的列表中，您會注意到已調用的鏈接：
   

   

   
   如果您複製鏈接，您可以看到它包含位置名稱和其他幾個參數。
   

    https://openweathermap.org/data/2.5/find?callback=jQuery19103887954878001505_1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

5. 當您將鏈接粘貼到瀏覽器的地址欄時，您應該會看到 API 回复：
   

    jQuery19103887954878001505_1542285819413({"message":"accurate","cod":"200","count":1,"list":[{"id":3096472,"name":"Katowice","coord":{"lat":50.2599,"lon":19.0216},"main":{"temp":281.69,"pressure":1031,"humidity":61,"temp_min":281.15,"temp_max":282.15},"dt":1542285000,"wind":{"speed":3.6,"deg":50},"sys":{"country":"PL"},"rain":null,"snow":null,"clouds":{"all":90},"weather":[{"id":804,"main":"Clouds","description":"overcast clouds","icon":"04d"}]}]})

6. 有點亂，但是如果你取出括號的內容，用數據格式化程序運行它，你會看到一個有意義的結構：
   

    { "message":"accurate", "cod":"200", "count":1, "list":[ { "id":3096472, "name":"Katowice", "coord":{ "lat":50.2599, "lon":19.0216 }, "main":{ "temp":281.69, "pressure":1031, "humidity":61, "temp_min":281.15, "temp_max":282.15 }, "dt":1542285000, "wind":{ "speed":3.6, "deg":50 }, "sys":{ "country":"PL" }, "rain":null, "snow":null, "clouds":{ "all":90 },

7. API 的回復是一個包含當前天氣狀況信息的數據結構——您應該可以輕鬆解密大部分參數。 這種數據格式稱為 JSON 。 這是一個重要的符號，因為大多數現代 API 都使用它。 這堆標識符和括號有一個目的——應用程序解析結構良好的消息比解析隨機放置的文本更容易。

解釋一下我們剛剛在這裡所做的事情。

Open Weather Map 網站背後的 Web 應用程序從 API 獲取數據並將其顯示在網站上。

每次您輸入城市名稱並按搜索時，網站都會連接到具有特定鏈接的服務器，該鏈接包含城市名稱作為參數。

技術術語中的同一句話：網站背後的應用程序向API 端點發送請求，提供城市名稱作為參數。

然後，API 使用JSON格式的文本消息回复（發送API 響應）。

要創建 API 請求，您需要將其地址放在一起。 是的，地址是一個很好的類比。 要運送東西，您需要向快遞員提供：

• 城市，
• 街道和門牌號，
• 有時會提供一些關於如何到達辦公室的額外信息。

而且，要連接到 API，以此類推，您需要：

• https://openweathermap.org/ （鏈接）城市或根端點——在我們的例子中，一個起點，一個你想連接的服務器的互聯網地址。
• data/2.5/find (link) 街道號碼或路徑——決定了你想從 API 獲取的資源。
• ?callback=jQuery19103887954878001505 1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22& =1542285819418（鏈接）的額外信息或查詢參數-讓API服務器

這就是 API 的設計方式。 對於單個供應商，根端點通常保持不變，然後您需要弄清楚哪些路徑和查詢參數可用，以及 API 開發團隊在它們後面放置了哪些信息。

現在讓我們把黑客的帽子戴得更緊一點。 在我們的例子中，並非所有查詢參數都是獲取天氣數據所必需的。 嘗試刪除問號 ( ? ) 後的不同參數並檢查 Weather API 如何回复。

例如，您可以從請求鏈接中刪除callback開始：

 https://openweathermap.org/data/2.5/find?callback=jQuery19103887954878001505_1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

結果：

 https://openweathermap.org/data/2.5/find?q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

如果您與其他人一起玩，您會發現其中一些也是可選的。 實際上只有q和appid是強制性的：

 https://openweathermap.org/data/2.5/find?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

你怎麼知道什麼是強制性的，什麼是可選的？ 首先，您如何知道從何處獲取根端點和路徑？

API 文檔：開始前必讀

您總是需要先查看 API 文檔，以了解如何以正確的方式構建您的請求。

在我們的例子中，文檔 https://openweathermap.org/current 顯示了可用的端點。 它還解釋了所有響應數據字段——因此您甚至可以在發送請求之前找到 API 將回复的信息。

一個好的 API 文檔提供了關於如何創建簡單請求和轉向更高級內容的快速入門教程。 幸運的是，Open Weather API 有一個，我們現在就要使用它。

從頭開始創建 API 調用

讓我們總結一下我們的發現。 我們已經向 API 發送了一個請求。 通過嗅探 OpenWeatherMap 在幕後所做的工作，我們找到了正確的鏈接。 這種方法稱為逆向工程，通常很難或根本不可能。

此外，大多數時候，API 提供商會禁止用戶過度使用此選項。 這就是為什麼我們應該學習如何按照規則（即文檔）“調用”API。

一種方法是對其進行編碼。 但由於我們不是編碼員（還沒有！ ），我們將使用使這更容易的工具。 如此簡單，即使是軟件開發人員也可以將它放在他們的工具帶下。

正如所承諾的，我們不會離開瀏覽器。 但是我們需要安裝一個擴展程序（僅限 Chrome）——Postman。 這個簡單的插件將您的瀏覽器變成一個 API 連接器。

好的，現在我們有了一個工具，讓我們看一下文檔，看看我們如何獲取特定城市名稱https://openweathermap.org/current#name的當前天氣狀況。

文檔說我們應該使用以下端點： api.openweathermap.org/data/2.5/weather?q={city name}

當我們分解它時，我們會得到以下元素：

• 根端點： api.openweathermap.org
• 路徑： data/2.5/weather
• 查詢參數： q={city name} （這個概念意味著我們應該用特定的城市名稱替換大括號）

讓我們把它放到 Postman 中。 該過程歸結為三個簡單的步驟：

1. 單擊頂部菜單中的“請求”。
   

   

2. 命名您的請求並在底部的部分中提供目錄名稱。

   

3. 粘貼您要調用的 API 端點，單擊“發送”，您應該會在“響應”部分看到 API 響應：

   

恭喜！ 您剛剛成功呼叫了您的冷杉……等一下！ 讓我們注意API響應：

它不是我們以前見過的充滿天氣信息的 JSON。 401 和無效的 API 密鑰到底意味著什麼？ 我們的文檔有錯嗎？

驗證

未經您的許可，您不會讓任何人進入您的雞尾酒櫃，對嗎？ 同樣，API 提供商也希望控制其產品的用戶，以保護其免受惡意活動的侵害。 什麼是惡意活動？ 例如，同時發送多個 API 請求，這會使服務器“過熱”並導致其他用戶停機。

如何控制訪問？ 就像你保護你的飲料一樣！ 通過使用密鑰——API 密鑰。

如果您訪問 Weather API 文檔中的如何開始指南，您會注意到如何獲取密鑰。 立即註冊並檢查您的收件箱。

那麼現在的問題是如何使用密鑰？ 根據文檔，這很容易，只需將密鑰複製並粘貼到端點 URL 的末尾（不帶大括號）。

 api.openweathermap.org/data/2.5/weather?q=Katowice&appid={your API key}

然後再次點擊發送。 在這裡，我們現在可以看到 API 響應！

但是您可以使用 Postman 從 API 中獲得更多信息。 準備好成為真正的 API 黑客了嗎？

API 參數：獲取定制響應

通常，API 端點具有一些實用功能，可用於調整 API 響應，例如，如果您需要更好的數據格式或希望以特定順序獲取數據。 這些選項通常隱藏在您可以在文檔中找到的一些參數後面。

查詢參數只是您在端點地址添加的結構化文本，具有以下模式：

1. 路徑後的問號 ( ? )，
2. 參數名稱，
3. 等於 ( = ) 符號，
4. 參數值，
5. 與號 ( & ) 和其他符號遵循第 2-4 點（通過這種方式，您可以添加任意數量的參數）。

以我們的第一個請求為例：

 https://openweathermap.org/data/2.5/find?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

重要提示：查詢參數的順序無關緊要。

 ?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

以上與以下相同：

 ?appid=b6907d289e10d714a6e88b30761fae22&q=Katowice

如前所述，查詢參數在 API 文檔中進行了描述。 以下天氣 API 文檔摘錄向您展示瞭如何以不同的單位（英製或公制）獲取溫度：

嘗試使用 Postman 發送這兩個選項以查看結果差異。 請記住在端點地址的末尾添加您的 API 密鑰。

注意：總是花一些時間研究文檔並找到可以為您或您的開發團隊節省大量時間的參數。

API 請求選項：如何向 API 發送數據

到目前為止，我們一直在從 API 獲取信息。 如果我們想在 API 後面的數據庫中添加或修改信息怎麼辦？ 請求方法就是答案。

讓我們再看看 Postman。 您可能已經註意到 API 端點地址旁邊有一個大寫的 GET 標籤。 這代表四種請求方法之一。 GET意味著我們想從 API 中獲取一些東西（感謝船長），這是一個默認選項。 還有哪些其他選擇？

還在糾結？ 讓我們轉到示例。

API POST：如何在 API 中創建記錄

我們無法使用 Wea​​ther API 創建或更新任何內容（因為它是只讀的），因此我們需要找到一個不同的用於測試目的。

讓我們提出一些更面向業務的示例。 我們將模擬以下場景：

如果下雨，請為您的客戶製作一張“振作起來”的折扣券。

我們將使用 Voucherify，它提供了一個 API，用於為任何電子商務系統創建和跟踪促銷活動。

免責聲明：我是 Voucherify 的聯合創始人。 我很高興回答您有關設計和實施數字促銷的問題，當然還有我們的 API 。

我們已經知道如何從前面的示例中獲取它們，所以讓我們專注於創建憑證：

1. 正如我們所說，我們應該始終從文檔開始。
2. 快速入門指南告訴我們獲取 API 密鑰。
   注意：您可以使用快速入門指南中的測試密鑰，而不是創建帳戶——我們將在一分鐘內向您展示如何操作。
3. 現在，讓我們了解如何創建折扣券。 在 Voucherify 中，這種促銷被表示為“優惠券”。
4. 從文檔中，您將了解到要創建憑證，您需要調用 POST 方法到/vouchers端點。
5. 在 Postman 中創建一個新的請求。
6. 將方法更改為 POST。
   

   

7. 粘貼 Voucherify 端點https://api.voucherify.io/v1/vouchers/並單擊發送。
   

   

8. 哦，快照，我們無權調用此端點。 您可能已經猜到了，我們需要提供 API 密鑰。
   
   Voucherify 的做法略有不同。 而不是將它們作為查詢參數，您應該將它們放在標題中。 這是一種常見的方法，因為以這種方式實現和維護鍵比將它們附加為查詢參數更容易。
   
   如圖所示添加密鑰，然後單擊發送。 請注意，Voucherify 需要兩個密鑰。 以下是您可以用於本教程目的的：
   X-App-Id: 8a824b12-0530-4ef4-9479-d9e9b9930176 X-App-Token: 9e322bac-8297-49f7-94c8-07946724bcbc

   

9. 我們收到另一條錯誤消息，這次它說有效負載不能為空。
   

   

   
   什麼是有效載荷？ 與 GET 的情況一樣，我們想要檢索一些信息，使用 POST 我們需要發送一些東西，我們發送的消息稱為有效負載，它通常是一個 JSON 文件。
   
   現在 Voucherify API 抱怨我們沒有提供一個，這意味著它不能創建一個憑證，因為我們沒有告訴它應該創建什麼樣的憑證。 所以現在怎麼辦？ 回到文檔！
10. 讓我們找出這個請求需要什麼樣的信息才能成功。 我們可以在列表中看到很多選項。
    

    

    
    一個參數（類型）是必需的，另一個是可選的。 假設這將是 20% 的折扣，適用於前 100 位客戶，即日到期。 現在我們需要找到負責此折扣功能的參數，並將它們組合成對 Voucherify API 不穩定的格式。 正如您在上面的示例中看到的，您應該使用的 JSON 表示法如下所示：

     { "type":"DISCOUNT_VOUCHER", "discount":{ "percent_off":20.0, "type":"PERCENT" }, "expiration_date":"2018-12-03T23:59:59Z", "redemption":{ "quantity":100 }

11. 要在 Postman 中設置有效負載，請將 JSON 消息粘貼到正文選項卡中。 從可用負載格式列表中選擇“原始”類型和 JSON，然後使用發送確認。
    

    

12. 瞧！ Voucherify 已成功創建了我們的 20% 折扣優惠券（因為我們正在使用測試帳戶，所有生成的代碼都以“voucherify.io-”前綴開頭）。 營銷團隊現在可以與客戶共享代碼，並且 Voucherify 將在他們來您的商店兌換它時自動驗證它。
    

    

    
    但是我們怎麼知道這是一個成功的請求呢？ 首先，我們可以看到 Voucherify 向我們發送了一條消息，根據他們的文檔，該消息看起來像是一個正確的 API 響應。 其次，Postman 顯示狀態200 OK——這意味著我們的請求成功。 為什麼是 200 以及狀態如何？

API 狀態代碼和錯誤消息

您將與之交互的大多數 API 都是基於 HTTP 的。 HTTP 是一種標準化 Internet 上各種客戶端應用程序和服務器之間的通信的協議。

HTTP 的關鍵元素之一是狀態碼。 通過了解您（或您實際實現的系統）的狀態代碼，可以立即了解您的請求發生了什麼。 當您輸入錯誤的鏈接時，您可能會遇到最流行的狀態代碼之一 - 404

但是還有更多，最終用戶通常看不到它們。 它們的範圍從 100+ 到 500+。 一般來說，數字遵循以下規則：

• 200+表示請求成功；
• 300+ 表示請求被重定向到另一個 URL；
• 400+ 表示發生了源自客戶端應用程序的錯誤；
• 500+ 表示發生了源自服務器的錯誤。

如果您可以再次執行這些步驟，您會看到當我們沒有提供 API 密鑰時，Voucherify 回復了 401 Unauthorized。 或 400 Bad Request 當沒有創建憑證請求所需的有效負載時。 最後，我們收到 200 作為 API 調用成功的標記。

如果您對 HTTP 狀態碼的含義感到好奇，那麼沒有比 HTTP Cats（或者這篇文章）更好的地方了。

概括

不斷增長的數據量和對構建產品速度的需求推動 API 成為數字團隊的通用語言。 要基於 API 優先系統設計系統，請確保您了解供應商的產品。 這個動手測試指南是這樣做的一個很好的起點。 它將幫助您在將 API 功能交給您的教學團隊之前探索 API 功能，從而節省他們的精力 - 以及您的精力。

延伸閱讀

• “面向非開發人員的電子商務 API 簡介”，Scott Brinker
• “超越 Headless CMS — 認識 Headless Commerce”，Michal Sedzielewski，Voucherify
• “如何使用 API 優先平台更快地構建您的網站”，Michal Sedzielewski，Medium
• “如何使用您的 API 優先平台讓您的原型產品為生產做好準備，”Michal Sedzielewski，Medium
• “如何使用雲更快地構建應用程序”，Michal Sedzielewski，Hacker Noon