API接口入門(一):讀懂API接口文檔
對于很多產品小白或求職者而言,API接口是一個產品和研發領域的專業術語,大家可能在文章或者PRD中都已經有接觸過API接口的概念。
實際上,接口的應用已經非常廣泛和成熟,這個概念主要活躍在公司內部的各系統之間的銜接和對接以及公司間合作的場景。如果你可以認真看完這篇文章,我相信你們對API接口的認識會更深入,甚至超過90%的小白和求職者。
本文目錄:
- API接口是什么?
- 為什么我們需要API接口?
- API接口的核心
一、API接口是什么?
我們來以一個常見的數學公式理解API,比如y=x+2,當x=2的時候,y=4,對么?
那此時,我們把y=x+2稱為接口,x=2稱為參數,y=4稱為返回結果,那這個接口的功能就是能把我們輸入的數加上2(注意:這里你可以發現接口自身是帶有邏輯的)。
類比地,我們來理解一個常見的場景,比如現在有一個可以把經緯度轉化為城市的接口,那當我輸入經度是55°,緯度是88°的時候,接口通過自己的邏輯運算,返回結果告訴我:杭州市。
這樣你就可以清晰地了解百度百科的官方解釋了,接口就是預先定義的函數邏輯,他是供其他系統請求,然后返回結果的一個東西。
二、為什么我們需要API接口?
背景:我們的業務系統涉及多方多面,如果要一個公司或者一個系統把所有業務都做完,那未免工作量太大了吧?并且如果其他系統或公司有更好的運算邏輯,那我們在設計功能的時候可以考慮利用接口進行開發。
核心需求:利用現有接口可以降低開發成本,縮短開發成本。
舉個例子:比如我是打車的APP,現在我需要在我的頁面上展現地圖的功能,對于我司而言,新做地圖功能未免成本過高,那我們可以在高德開放平臺或者百度地圖的開放平臺,找到地圖API,這樣的話我們只需要購買高德的服務,部署調用高德地圖API,這樣就可以快速在我們頁面上線地圖功能了。
三、API接口的核心
對于小白而言,初看API文檔可能是一頭霧水的——從哪里看,怎么看,看什么是擺在面前的問題。
其實對于產品經理而言,我們應該更關注這個公司可以提供什么樣的API接口服務,比如我知道高德可以提供地圖API,規劃路線的API,這樣的話在我們設計功能和工作中就可以想到調用他們的服務或者參考。
所以產品小白們看不懂也不用過于擔心,未來工作中你也會更深入了解清楚,因為看懂并不復雜,以下是API接口的核心點,所有的說明文檔離不開這5個核心點。
以下說明均以微信開放平臺為例說明,文末有各開放平臺的地址,大家有空可以去學習。好了,事不宜遲,現在我們來建立一個場景。
我們現在有一個APP,需要用戶在購買的時候調起微信支付的API,完成購買。請各位自動進入這個場景,把自己當作一位產品經理。
1. 接口地址
現在Now,用戶點擊付款,我們需要告訴微信,我們要調起你們的收銀臺啦!但,去哪里告訴呢?這就需要接口地址了,也就相當于向微信的這條鏈接傳輸指定的數據。
一個鏈接地址不是我們理解的一個頁面,你可以理解是一個電話號碼,小白們要改變這個觀念。
此時我們可以看到接口文檔告訴我們鏈接是如下這條,那我們現在已經撥通微信的電話了。
2. 請求參數(報文)
我們現在需要告訴微信,你想調用收銀臺對吧。那我們需要寫下來,此時生成的叫做報文,也就是你想告訴這個接口的內容是什么?相當于前文函數的輸入x=2。
一般來說,報文的格式和內容都是按接口文檔規定的。如下文就是微信開放平臺對調起收銀臺的報文要求。
我們先來看前2個參數,你現在跟微信在對話,是不是應該先告訴微信,你是誰?這里微信的文檔告訴你應該要用應用ID+商戶號來確定你的身份,什么意思呢?
比如你是A商戶,下面有a,b,c三個APP,所以微信要知道你是哪個商家,下面的哪個APP要用收銀臺。這是非常重要的,微信后面要把收到的錢打到對應的賬戶以及統計數據等。
那我們就在報文里面寫下這兩句話:
- <appid>wx2421b1c4370ec43b</appid>(我的應用ID是wx2421…….)
- <mch_id>10000100</mch_id>(我的商戶號是10000…….)
好了,現在微信知道你是誰了,那你要告訴微信,你需要微信支付幫你收多少錢對吧?這里定義了貨幣類型和總金額,也就是收什么貨幣,收多少錢。
這里你看,貨幣類型的必填寫了否,也就是說你也可以不告訴微信支付貨幣類型是什么,因為他在后面備注了默認是人民幣。
好的,那我們寫下兩段報文
- <free_type>CNY</ free_type >(我要收人民幣)
- <total_fee>1</total_fee>(我要收1元)
好了,現在微信知道你是誰,也知道要收多少錢了,那接下來微信支付要把收錢結果告訴你呀,因為你得知道用戶是成功支付了才能繼續發貨,服務啊等等的。所以這里我們用到通知地址,就是告訴微信,等下完事了他去哪里告訴你支付結果。那我們把地址寫好:
<notify_url>http://wxpay.wxutil.com/pub_v2/pay/notify.v2.php</notify_url>
3. 返回結果
剛剛微信支付已經去收款了,現在他要在我們留下的通知地址中,告訴我們結果了。結果無非是兩種:成功收款?收款不成功?
(1)成功
很順利,現在用戶成功付錢了,并且微信也把成功的消息告訴我們了,并且他還把用戶支付的一些信息也告訴我們。
那這里就是微信支付成功收款后告訴我們的信息。
應用APPID,商戶號:告訴你我成功扣款的是哪家商戶的哪個APPID的交易。
業務結果:成功或失敗
(2)失敗
在產品設計的時候,我們往往很關注失敗的情況,當收款失敗的時候,微信同時會告訴你失敗的原因,如下圖很好理解,失敗的原因有很多很多種,我們在設計的時候往往要分析每種失敗的原因,為每個失敗的原因設計頁面和用戶提示,以確保用戶能理解。
以上就是API接口基本運作模式的理解,下面我將繼續更新API接口的一些更為深入和細節的關鍵元素,如請求方式/簽名/加解密等等。
可供參考的開放平臺網站
微信支付:https://pay.weixin.qq.com/wiki/doc/api/index.html
高德平臺開放平臺:https://lbs.amap.com/
本文由 @就是愛睡覺 原創發布于人人都是產品經理。未經許可,禁止轉載
題圖來自Unsplash,基于CC0協議
很容易理解!很感謝!
太棒了,小白一下就懂了
感謝作者答疑解惑,想問一下我們產品經理就API接口需要向研發傳遞什么內容,做哪些工作。可以出一章答疑么?
我認為產品經理要做的是摸清楚合作方有什么API和關鍵返回結果,以及設計什么時候調用,并拿到結果后怎么處理。
可以分享嗎
看了好幾篇,這一篇說的是最清楚的,感謝
推薦試試 Apifox,好用很多。接口文檔+接口調試+數據 Mock+接口測試,功能齊全。 接口文檔和接口開發調試使用同一個工具,接口調試完成后即可保證和接口文檔定義完全一致。高效、及時、準確!
寫得太好了吧,對我們這種剛入行的小白太有用了
邏輯清晰,通俗易懂,對內容輸出者表示感謝~
真的通俗易懂,好棒,學習了,希望大大可以出關于兩個三方系統之間對接,產品經理要做的事案例
嗚嗚要哭了 寫的太好了!拯救我!
總的來說,通俗易懂!
非常好,把困惑我很久的API講懂了
全是干貨啊,小白太感動了,抱緊大腿
感謝,
寫的真不錯,學習了,感謝分享! 關注中……
寫的不錯
學習了,感謝分享
人民幣單位不是分嗎?為什么1會是“我要收1元”而不是“我要收1分”呢?
total_fee 1 /total_fee
產品經理需要設計字段名變量名等等嘛?
不是說五個核心嗎,我只看到三個核心,其他兩個是什么
消息通知
你好,可以公眾號上分享么?
ok
寫的很棒,如果有公眾號就更好了,看了評論區都是可以分享的,我這邊搬運一下,或注明原作者,和原文鏈接的
ok
我是產品小白,真的很好,可以分享嗎
ok
ok
通俗易懂
好文
贊贊贊,通俗易懂,速速更新后面的文章 ??
?? 正在看接口問題,,,看完覺得簡單多了,