原則上API接口設計一般出現在開發的詳細設計中，但是隨著諸多公司建立開放平臺，產品經理也逐漸需要能理解API接口，尤其是做平臺性的產品，還要學會定義接口。本文就關于產品經理在設計接口中需要定義什么、需要注意什么來展開陳述。

看到人人都是產品經理社區已經有關于API接口的相關介紹，因此本文就不做過多的關于API接口概念方面的介紹。

一、了解API的常識

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

1. 常用的通信協議

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

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

• 科大訊飛的物體識別請求URL：http://tupapi.xfyun.cn/v1/currency
• 百度的菜品識別請求URL：?https://aip.baidubce.com/rest/2.0/image-classify/v2/dish

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

2. 接口的請求方式

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

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

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

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

3. 接口響應機制

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

（1）刷臉支付：以支付寶為例，使用之前需要按照步驟采集人臉，后臺會調用人臉注冊將當前人臉注冊進人臉庫并和該支付寶賬號信息綁定，這一步人臉注冊通常是同步接口，因為不會要求用戶在APP前等待太久，需要及時返回注冊成功信息；

（2）客流系統：現在商超使用的客流系統一般已經采用人臉識別取代頭肩模型，這樣不僅可以統計人數還可以統計人次，其中對于首次識別的陌生人臉通常需要注冊進陌生人臉庫，這里的人臉注冊一般為異步接口，因為大型商超每天數十萬客流且對于陌生人無會員信息，所以不需要實時注冊，只要進入隊列能在當日24小時內注冊完即可；

小結

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

二、核心業務字段&接口約束

產品經理雖然不需要定義API所有的字段信息，但是跟業務需求有關的字段產品經理需要明確清晰。

1. 入參

（1）鑒權字段信息

調用第三方平臺接口通常需要進行接口鑒權，服務端判斷用戶端是否有調用接口的權限；這里跟產品經理相關的是作為產品需要設計應用管理，包括：應用列表、應用創建、應用詳情、應用配置、應用刪除等操作；以百度AI平臺，應用列表如下：

其中AppID、API Key和Secret Key為創建應用時自動生成，接口鑒權所需要的access_token必須通過API key和Secret key請求服務端獲取。

（2）核心業務字段

產品經理需要根據業務需求明確接口入參中需要哪些字段信息以及字段支持的類型，以百度AI平臺的菜品識別為例：
業務需求：識別圖片中是哪種菜品；

產品需求：

1. 輸入圖片，圖片支持通常采用base64和URL格式；
2. top_num，提高接口的通用性，方便用戶后續場景擴展，因此支持配置返回菜品數量且排序；
3. 閾值，開放識別閾值，方便用戶根據實際識別效果調整，提高準確率；

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

（3）字段信息約束條件

字段約束條件是為了保證接口的安全性，這點是產品經理跟業務方溝通達成一致后提供給開發小伙伴的；仍然以上面的菜品識別為例：

1. 圖片需要限制文件大小和分辨率大小，文件大小只需要上限，分辨率大小需要包括上限和下限，下限是為了保證算法效果，比如在目標檢測中小目標容易檢測失??；
2. top_num需要限制下限，不得小于0，不設上限，可以接受算法返回的所有結果；
3. 閾值根據格式確定，可以是0-100，可以是0-1；

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

2. 出參

調用接口就會有返回信息，產品需要根據業務需求定義返回的核心字段信息，這次以百度AI開放平臺手勢識別為例，其中跟業務需求相關的關鍵字段包括：

• result_num、result，即一張圖片中識別的手勢結果數量，和具體的手勢信息；
• result為json數組，包括手勢的類別、手勢檢測框的位置信息【一般識別類算法底層是檢測+識別兩步】、和手勢類別的置信度；
• 其中result中的一些字段信息，產品可以根據業務需求進行增減，比如目標檢測框的位置信息，一般業務不需要就可以省略；

三、接口限流

接口限流也是為了保障系統的安全性，因為有時業務方因為業務擴展導致調用量激增，容易引起服務端宕機；限流就類似于電閘的保險絲保證請求量超過接口上限時系統可以拒絕請求或排隊，以此保證系統的安全性；

產品經理需要實現對業務充分評估，給出合理評估量，如TPS（每秒處理的請求量）；這樣既不會造成系統資源的浪費，也保證業務正常運行；

注：與上面接口響應機制對應，同步接口一般需要給出峰值tps和響應時間，異步接口需要給出日調量即可；

四、接口測試

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

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

（2）業務需求覆蓋，即接口輸入輸出是否遵循產品需求文檔描述；

（3）邊界規則遵循，即接口是否滿足業務規則和字段約束條件；

（4）性能條件，通常接口上線前需要經過壓測達到性能指標才可，包括某并發量下的tps和耗時等；

結語

以上即是本人作為產品經理對于API設計時經常需要和開發、業務討論的關鍵點和注意點~~

#相關閱讀#

《三步法完成AI產品需求分析》

《如何做一款SDK產品？》

本文由 @Eric_d 原創發布于人人都是產品經理。未經許可，禁止轉載

題圖來自Unsplash，基于CC0協議