做產(chǎn)品經(jīng)理會調(diào)研各式各樣的第三方需求能力。
以滿足產(chǎn)品提供用戶所需要的功能，比如第三方登錄、圖像識別、風(fēng)控算法，都有專注的服務(wù)廠商。
通過接入第三方能力，企業(yè)無需自己花時間和精力投入在具有較高技術(shù)壁壘或時間成本的需求上。就算企業(yè)自己做，也做不好。
所以，產(chǎn)品經(jīng)理學(xué)會看API接口文檔，是一項產(chǎn)品經(jīng)理的基本功，可以提升產(chǎn)品設(shè)計質(zhì)量、以及和開發(fā)溝通效率。
那么，一個合格的接口文檔包含什么內(nèi)容？
▲ 接口文檔范圍
有了接口文檔，我們可以知道第三方能力的功能邏輯、功能的邊界、和接入的條件。比如要接口當(dāng)天的天氣接口信息，可以查看下面的接口。
比如萬年歷的接口文檔描述了接口的傳輸數(shù)據(jù)是當(dāng)天詳情。
▲ 萬年歷的能力描述
接口文檔的編寫規(guī)范
各個公司甚至一家公司的不同項目組，接口文檔都可能不一樣。項目成員的前后端開發(fā)工程師會去定義接口，并且隨著需求變化，接口文檔也需要不斷維護(hù)。
所以經(jīng)常有不懂接口文檔的產(chǎn)品經(jīng)理如果讓開發(fā)同學(xué)你把后臺功能給其他部門直接用、或者某某客戶端你把你的app直接給某某部門后臺用。
這個時候，開發(fā)的拳頭就捏緊了。
在一家公司不同項目下，接口仍然有規(guī)范不一致的情況，更何況公司之間的數(shù)據(jù)交流。這也是為什么有產(chǎn)品經(jīng)理的公司，都不會選擇外包。外包開發(fā)意味著后期維護(hù)在接口、規(guī)范上都是不清楚的，難以搞清楚對方的撰寫代碼思路和潛在問題。
接口規(guī)范集中在4點維度上去做規(guī)范
1.接口方法新增post
修改put
刪除（delete）
獲?。╣et）
通過上面4個定義接口的權(quán)限。
2.URI定義
以/a開頭，如果你的賬戶涉及到需要登錄權(quán)限、比如我們的微信開放平臺、第三方單點登錄，則需要/u。如果是通過后臺要查詢數(shù)據(jù)庫列表，則以/search結(jié)尾。如果是查詢前臺的列表則以/list結(jié)婚
3.請求參數(shù)和返回參數(shù)
兩個類型參數(shù)都分為5列：字段、說明、類型、備注、是否必填。
▲ 接口的參數(shù)案例
字段：類的屬性
說明：中文解釋字段什么意思
類：屬性類型
有string（字符串）、number（整數(shù)）、object（對象）、arrar（數(shù)組）四種類型。
備注：接口的能力或邏輯解釋，或者可以寫一下列子，有的情況有列子會讓開發(fā)人員看得懂一些。比如json
返回參數(shù)：返回參數(shù)和產(chǎn)品經(jīng)理的異常是非常相關(guān)的。比如
只會返回接口調(diào)用成功或失敗
返回某些參數(shù)
返回列表
上面3種返回形式都包含內(nèi)容有區(qū)別。
第一種
新增、刪除、修改等，只需要一個結(jié)果即可。
第二種
結(jié)構(gòu)體有2個，第一個是code/mesaeg/dat ，第二個是data里寫返回的參數(shù)，data是object類型
第三種
過于偏向開發(fā)知識，就不再敘述。
接口文檔主要有什么
互聯(lián)網(wǎng)企業(yè)要開放能力給其公司或開發(fā)者使用，就需要創(chuàng)建接口和定制接口規(guī)范。常見的產(chǎn)品形態(tài)有開放平臺這類形式。通過開發(fā)者注冊賬戶，創(chuàng)建單獨秘鑰，再提供接口允許開發(fā)者獲取能力。如下是喜馬拉雅的開放平臺下提供的音頻能力的SDK、API接入文檔。在接口文檔里面有前面提到的規(guī)范內(nèi)容。
▲ 喜馬拉雅接口文檔
請求后會有響應(yīng)。在代碼層面會有如下的顯示規(guī)則
serid Long 用戶ID
usernick String 用戶登錄名
sessionkey String 用戶會話key
示例
請求
XXXX
響應(yīng)
{usersession11:
{userid:12512313,
usernck: name1 ,
sessionkey:2122323232332435353,
}}
響應(yīng)有結(jié)果，并且顯示調(diào)用成功則表示接口調(diào)通。
開放平臺文檔字段說明
第一：請求
說明請求地址，告訴如何調(diào)用接口
第二：調(diào)用秘鑰
比如喜馬拉雅要求申請秘鑰，走開放平臺賬戶協(xié)議進(jìn)行注冊。
第三：API測試
接通后會顯示什么結(jié)果，如何知道接口是否接通？就需要在接口文檔里面知道成功的參數(shù)
▲ 請求測試
同理可以在微信開放平臺上可以看到
▲ 微信開放平臺的接口文檔描述
多個接口文檔組成的接口目錄讓產(chǎn)品經(jīng)理和開發(fā)者快速查詢功能點，以集成到自己的產(chǎn)品中。所以產(chǎn)品經(jīng)理做第三方能力調(diào)研，最多時間的就是去看對方的接口文檔。
包括對接口的描述，比如下圖是地理位置獲取?？梢钥吹皆谠摻涌谙?，可以看到地理位置獲取失敗、成果的提示。
▲ 微信公眾平臺提供位置信息的接口
看完覺得寫得好的，不防打賞一元，以支持藍(lán)海情報網(wǎng)揭秘更多好的項目。
感謝您的支持，我會繼續(xù)努力的!
打開支付寶掃一掃，即可進(jìn)行掃碼打賞哦
手機(jī)直接保存圖片,掃一掃識別二維碼,即可進(jìn)行掃碼打賞哦
