API接口設(shè)計，需要注意這4點(diǎn)

原文 | http://www.woshipm.com/pd/2772820.html

原則上API接口設(shè)計一般出現(xiàn)在開發(fā)的詳細(xì)設(shè)計中，但是隨著諸多公司建立開放平臺，產(chǎn)品經(jīng)理也逐漸需要能理解API接口，尤其是做平臺性的產(chǎn)品，還要學(xué)會定義接口。

本文就關(guān)于產(chǎn)品經(jīng)理在設(shè)計接口中需要定義什么、需要注意什么來展開陳述。

看到人人都是產(chǎn)品經(jīng)理社區(qū)已經(jīng)有關(guān)于API接口的相關(guān)介紹，因此本文就不做過多的關(guān)于API接口概念方面的介紹。

一、了解API的常識

在做接口設(shè)計時，如果是新手，建議多參考并了解不同開放平臺的接口樣式，比如百度、曠視、騰訊等，從中可以發(fā)現(xiàn)一些共識；

1、常用的通信協(xié)議

調(diào)用第三方平臺接口需要進(jìn)行系統(tǒng)間的通信，目前常用的協(xié)議是http和https；簡單理解https是http的加密版，可以將用戶到服務(wù)端請求的信息進(jìn)行加密，避免因明文傳輸被截獲而獲知用戶信息。

基于http協(xié)議的接口具有輕量級、跨平臺、和跨語言的特點(diǎn)，為了適應(yīng)不同的開發(fā)者，目前各個第三方平臺都會提供基于各種常用語言的接口形式，因此大多采用http或https協(xié)議；舉例，百度、科大訊飛：

• 科大訊飛的物體識別請求URL：http://tupapi.xfyun.cn/v1/currency

• 百度的菜品識別請求URL：https://aip.baidubce.com/rest/2.0/image-classify/v2/dish

筆者查閱了百度、騰訊、曠視、阿里的云平臺發(fā)現(xiàn)在視覺方面均都采用的是https協(xié)議；對于視覺，圖片數(shù)據(jù)本身包含的信息就很豐富，尤其是人臉，因此采用https還是有利于保護(hù)用戶隱私信息的。

2、?接口的請求方式

了解接口的請求方式有助于了解用戶端和服務(wù)端間的交互方式，基于http協(xié)議的常用請求方式是post和get；兩者的主要區(qū)別如下：

（1）直觀區(qū)別：get請求方式是將請求參數(shù)放到url中，post是將參數(shù)放到requst body中，所帶來的的直接影響是get的請求參數(shù)存在長度限制，post無限制；其次是get將參數(shù)放到url中安全性弱于post；

（2）深度區(qū)別：get請求方式用戶端和服務(wù)端只產(chǎn)生一次交互，post請求方式用戶端會和服務(wù)端產(chǎn)生兩次交互，舉例：快遞小哥是用戶端，你是服務(wù)端，則get就像常來你們小區(qū)和你認(rèn)識的快遞員直接將快件送到你家，你跟他說聲謝謝；post就像新來的快遞員先打個電話問下你在家嗎？你告訴他你在家呢，過了5分鐘他將快遞送到你家了，你跟他說聲謝謝；

目前百度、騰訊、曠視的圖像識別接口均采用的是post請求方式

3、接口響應(yīng)機(jī)制

最后了解接口的響應(yīng)機(jī)制：同步接口和異步接口；簡單理解同步接口即實(shí)時返回消息給調(diào)用方，異步接口就是可以延遲返回消息給調(diào)用方；實(shí)時性要求高的且只能線性工作的需要采用同步接口，其他可以優(yōu)先使用異步接口；當(dāng)然不同的場景，同樣的服務(wù)接口會被要求同步或異步；以人臉識別中的人臉注冊為例：

（1）刷臉支付：以支付寶為例，使用之前需要按照步驟采集人臉，后臺會調(diào)用人臉注冊將當(dāng)前人臉注冊進(jìn)人臉庫并和該支付寶賬號信息綁定，這一步人臉注冊通常是同步接口，因?yàn)椴粫笥脩粼贏PP前等待太久，需要及時返回注冊成功信息；

（2）客流系統(tǒng)：現(xiàn)在商超使用的客流系統(tǒng)一般已經(jīng)采用人臉識別取代頭肩模型，這樣不僅可以統(tǒng)計人數(shù)還可以統(tǒng)計人次，其中對于首次識別的陌生人臉通常需要注冊進(jìn)陌生人臉庫，這里的人臉注冊一般為異步接口，因?yàn)榇笮蜕坛刻鞌?shù)十萬客流且對于陌生人無會員信息，所以不需要實(shí)時注冊，只要進(jìn)入隊(duì)列能在當(dāng)日24小時內(nèi)注冊完即可；

小結(jié)

以上關(guān)于API的接口常識在設(shè)計接口的時候，開發(fā)一般都會要求產(chǎn)品確定接口的響應(yīng)機(jī)制；其他的開發(fā)都會自己完成；但作為開放平臺的產(chǎn)品經(jīng)常會對接開發(fā)，多了解些常識既可以跟自己的開發(fā)有更多的共同語言溝通，也可以在對接用戶的時候可以跟用戶的開發(fā)簡單解釋。

二、核心業(yè)務(wù)字段&接口約束

產(chǎn)品經(jīng)理雖然不需要定義API所有的字段信息，但是跟業(yè)務(wù)需求有關(guān)的字段產(chǎn)品經(jīng)理需要明確清晰。

1、 入?yún)?/span>

（1）鑒權(quán)字段信息

調(diào)用第三方平臺接口通常需要進(jìn)行接口鑒權(quán)，服務(wù)端判斷用戶端是否有調(diào)用接口的權(quán)限；這里跟產(chǎn)品經(jīng)理相關(guān)的是作為產(chǎn)品需要設(shè)計應(yīng)用管理，包括：應(yīng)用列表、應(yīng)用創(chuàng)建、應(yīng)用詳情、應(yīng)用配置、應(yīng)用刪除等操作；以百度AI平臺，應(yīng)用列表如下：

其中AppID、API Key和Secret Key為創(chuàng)建應(yīng)用時自動生成，接口鑒權(quán)所需要的access_token必須通過API key和Secret key請求服務(wù)端獲取。

（2）核心業(yè)務(wù)字段

產(chǎn)品經(jīng)理需要根據(jù)業(yè)務(wù)需求明確接口入?yún)⒅行枰男┳侄涡畔⒁约白侄沃С值念愋停园俣華I平臺的菜品識別為例：

業(yè)務(wù)需求：識別圖片中是哪種菜品；

產(chǎn)品需求：

1. 輸入圖片，圖片支持通常采用base64和URL格式；

2. top_num，提高接口的通用性，方便用戶后續(xù)場景擴(kuò)展，因此支持配置返回菜品數(shù)量且排序；

3. 閾值，開放識別閾值，方便用戶根據(jù)實(shí)際識別效果調(diào)整，提高準(zhǔn)確率；

注意點(diǎn)：設(shè)計接口核心業(yè)務(wù)字段，要盡量提高接口的通用性，以此適配更多的用戶場景，比如top_num和閾值的開放，即泛化接口能力，將更多的主動權(quán)交由接口用戶配置。

（3）字段信息約束條件

字段約束條件是為了保證接口的安全性，這點(diǎn)是產(chǎn)品經(jīng)理跟業(yè)務(wù)方溝通達(dá)成一致后提供給開發(fā)小伙伴的；仍然以上面的菜品識別為例：

1. 圖片需要限制文件大小和分辨率大小，文件大小只需要上限，分辨率大小需要包括上限和下限，下限是為了保證算法效果，比如在目標(biāo)檢測中小目標(biāo)容易檢測失敗；

2. top_num需要限制下限，不得小于0，不設(shè)上限，可以接受算法返回的所有結(jié)果；

3. 閾值根據(jù)格式確定，可以是0-100，可以是0-1；

注：設(shè)置參數(shù)的一點(diǎn)小技巧，為了保證算法效果，有時算法會默認(rèn)設(shè)置參數(shù)，即用戶設(shè)置的閾值低于默認(rèn)參數(shù)，則不接受輸入，采用默認(rèn)，用戶是無感知的；

2、出參

調(diào)用接口就會有返回信息，產(chǎn)品需要根據(jù)業(yè)務(wù)需求定義返回的核心字段信息，這次以百度AI開放平臺手勢識別為例，其中跟業(yè)務(wù)需求相關(guān)的關(guān)鍵字段包括：

• result_num、result，即一張圖片中識別的手勢結(jié)果數(shù)量，和具體的手勢信息；

• result為json數(shù)組，包括手勢的類別、手勢檢測框的位置信息【一般識別類算法底層是檢測+識別兩步】、和手勢類別的置信度；

• 其中result中的一些字段信息，產(chǎn)品可以根據(jù)業(yè)務(wù)需求進(jìn)行增減，比如目標(biāo)檢測框的位置信息，一般業(yè)務(wù)不需要就可以省略；

三、接口限流

接口限流也是為了保障系統(tǒng)的安全性，因?yàn)橛袝r業(yè)務(wù)方因?yàn)闃I(yè)務(wù)擴(kuò)展導(dǎo)致調(diào)用量激增，容易引起服務(wù)端宕機(jī)；限流就類似于電閘的保險絲保證請求量超過接口上限時系統(tǒng)可以拒絕請求或排隊(duì)，以此保證系統(tǒng)的安全性；

產(chǎn)品經(jīng)理需要實(shí)現(xiàn)對業(yè)務(wù)充分評估，給出合理評估量，如TPS（每秒處理的請求量）；這樣既不會造成系統(tǒng)資源的浪費(fèi)，也保證業(yè)務(wù)正常運(yùn)行；

注：與上面接口響應(yīng)機(jī)制對應(yīng)，同步接口一般需要給出峰值tps和響應(yīng)時間，異步接口需要給出日調(diào)量即可；

四、接口測試

接口測試雖然是測試小姐姐的工作，測試內(nèi)容也覆蓋眾多，但是作為產(chǎn)品可以簡單了解以下內(nèi)容即可，如，

（1）接口可用性，即接口是否可以正常調(diào)用，正常返回結(jié)果，異常正確處理，正常返回錯誤碼等；

（2）業(yè)務(wù)需求覆蓋，即接口輸入輸出是否遵循產(chǎn)品需求文檔描述；

（3）邊界規(guī)則遵循，即接口是否滿足業(yè)務(wù)規(guī)則和字段約束條件；

（4）性能條件，通常接口上線前需要經(jīng)過壓測達(dá)到性能指標(biāo)才可，包括某并發(fā)量下的tps和耗時等；

結(jié)語

以上即是本人作為產(chǎn)品經(jīng)理對于API設(shè)計時經(jīng)常需要和開發(fā)、業(yè)務(wù)討論的關(guān)鍵點(diǎn)和注意點(diǎn)~~