本文轉載自CSDN博主「陪學」的原創文章
原文鏈接：https://blog.csdn.net/weixin_42058609/article/details/105147681
-------------------
日常產品開發過程中，涉及前后端數據交互的時候，往往會離不開接口調用，盡管產品經理一般不需要寫接口文檔（負責接口中間層產品經理除外），但對接口了解，對於需求溝通、需求傳達還是很有幫助的。
接口是什么？
API（ApplicationProgramming Interface）即應用程序接口。
可以認為 API 是一個軟件組件或是一個Web 服務與外界進行的交互的接口。從另一個角度說，API是一套協議，規定了我們與外界的溝通方式：如何發送請求和接收響應。
API的本質是根據調用者的輸入內容來返回一些其他內容。
舉個栗子，這和我們生活中接觸的USB接口的原理是類似的，我們知道接入某個接口就能實現某種功能，例如：U盤插入電腦USB接口就可以相互傳輸文件。
產品經理看懂接口文檔的意義
1）了解技術開放能力，產品設計更合理
例如，我們公司是做微信公眾號生態相關的產品的，微信開放了許多公眾號的接口，如果不了解微信的接口文檔，往往就不知道如何應用到自己的產品。
2）通過接口構建產品功能。
通過現有接口來搭建產品，通過對接口、技術的理解，能夠更深入地衡量產品的數據邊界，對針對性的進行產品特色功能設計。
接口組成
接口分為四部分:
1、方法:
新增(post) 修改(put) 刪除(delete) 獲取(get)
2、格式：
以/a開頭，如果需要登錄才能調用的接口后面需要加/u(如新增、修改；前台的用戶個人信息，資金信息等)，即：/a/u；中間一般放表名或者能表達這個接口的單詞；
get方法，如果是后台通過搜索查詢列表，那么以/search結尾，如果是前台的查詢列表，以/list結尾。
3、請求參數和返回參數，
都分為5列：字段、說明、類型、備注、是否必填
字段：類的屬性
說明：中文釋義；
類型：屬性類型；
備注：一些解釋，或者可以寫一下例子，比如負責json結構的情況，最好寫上例子（這里不是產品寫），好讓前端能更好理解；
是否必填：字段的是否必填。
4、返回參數結構的幾種情況
如果只返回接口調用成功還是失敗（如新增、刪除、修改等），則只有一個結構體：code和message兩個參數；
如果要返回某些參數，則有兩個結構體：1是code/mesage/data，2是data里寫返回的參數,data是object類型；
如果要返回列表，那么有三個結構體，1是code/mesage/data,data是object，里面放置page/size/total/totalPage/list 5個參數，其中list是Arrary類型，list里放object，object里是具體的參數。
接口請求方式
基於http協議的常用請求方式是post和get；兩者的主要區別如下：
（1）get請求方式是將請求參數放到url中，post是將參數放到requstbody中，
直接影響是get的請求參數存在長度限制，post無限制；其次是get將參數放到url中安全性弱於post；
（2）get請求方式用戶端和服務端只產生一次交互，post請求方式用戶端會和服務端產生兩次交互，
例：快遞小哥是用戶端，你是服務端，get就像常來你們小區和你認識的快遞員直接將快件送到你家，你跟他說聲謝謝；post就像新來的快遞員先打個電話問下你在家嗎？你告訴他你在家呢，過了5分鍾他將快遞送到你家了，你跟他說聲謝謝；
接口響應機制
接口的響應機制包括：
同步接口
異步接口
同步接口即實時返回消息給調用方，異步接口就是可以延遲返回消息給調用方；實時性要求高的且只能線性工作的需要采用同步接口，其他可以優先使用異步接口；
不同的場景，同樣的服務接口會被要求同步或異步，以人臉識別中的人臉注冊為例：
（1）刷臉支付：
以支付寶為例，使用之前需要按照步驟采集人臉，后台調用人臉注冊將當前人臉注冊進人臉庫並和該支付寶賬號信息綁定，這一步人臉注冊通常是同步接口，因為不會要求用戶在APP前等待太久，需要及時返回注冊成功信息；
（2）客流系統：
商超使用的客流系統一般已經采用人臉識別取代頭肩模型，這樣不僅可以統計人數還可以統計人次，其中對於首次識別的陌生人臉通常需要注冊進陌生人臉庫，這里的人臉注冊一般為異步接口，因為大型商超每天數十萬客流且對於陌生人無會員信息，所以不需要實時注冊，只要進入隊列能在當日24小時內注冊完即可；
關於API的接口在設計時，開發一般會要求產品確定接口的響應機制；其他的開發都會自己完成；
很多產品經理剛接觸API接口工作時，腦子一片空白，不理解接口（API）是什么，更看不懂接口開發文檔。那么，作為一個不懂技術的產品經理，該如何看懂接口文檔。
API文檔結構
API接口文檔一般分為接口描述、接口地址、請求方法、請求參數、相應內容、錯誤代碼、實例幾個部分。
1、接口描述
簡單描述接口的邏輯和作用
2、接口地址
接口的正式url和接口測試的url，需求方通過調用接口url，獲取響應內容
3、請求方法
一般來說，接口最常見的請求方法為GET和POST兩種方式，即讀接口和寫接口。通過這兩種方式，實現對數據的增刪查改。增刪改本質都是寫的動作。
4、請求參數
即需要請求的字段名的名稱和規則：都是哪些字段，字段的類型是什么，是否必填字段等等
5、響應內容
接口返回的字段名稱和規則。
注意：大部分開發往往不會把所有的字段羅列，只會列出比較重要的字段。當你發現，接口文檔中沒有你需求的字段，別着急找開發，可以看下實例中，有沒有需求的字段。
6、錯誤代碼
對接口的錯誤用代碼進行歸類，以便能快速找到錯誤原因，解決問題。
7、實例
實際調用時的響應的內容。
核心業務字段&接口約束
產品經理雖然不需要定義API文檔里所有的字段信息，但是跟業務需求有關的字段產品經理需要明確清晰。
下面就來看看API文檔中的核心業務字段與接口約束。
1. 入參
（1）鑒權字段信息
調用第三方平台接口通常需要進行接口鑒權，服務端判斷用戶端是否有調用接口的權限；產品經理設計應用管理時，要了解：應用列表、應用創建、應用詳情、應用配置、應用刪除等操作；
以百度AI平台為例，應用列表如下：
AppID、API Key和Secret Key為創建應用時自動生成，接口鑒權所需要的access_token必須通過API key和Secret key請求服務端獲取。
（2）核心業務字段
產品經理要根據業務需求明確接口入參中需要哪些字段信息以及字段支持的類型，
以百度AI平台的菜品識別為例：
業務需求：
識別圖片中的菜品；
產品詳細需求：
用戶輸入圖片，圖片支持采用base64和URL格式；top_num
top_num，提高接口的通用性，方便用戶后續場景擴展，因此支持配置返回菜品數量且排序；
閾值，開放識別閾值，方便用戶根據實際識別效果調整，提高准確率；
注意點：設計接口核心業務字段，要盡量提高接口的通用性，以此適配更多的用戶場景，比如top_num和閾值的開放，即泛化接口能力，將更多的主動權交由接口用戶配置。
（3）字段信息約束條件
字段約束條件是為了保證接口的安全性，這點是產品經理跟業務方溝通達成一致后提供給開發小伙伴的；
以菜品識別為例：
圖片要求：采用base64圖片編碼、大小不超過4M，最短邊大於15PX，最長邊小於4096px，圖片格式：jpg/png/bmp
圖片需要限制文件大小和分辨率大小，文件大小只需要上限，分辨率大小需要包括上限和下限，下限是為了保證算法效果，比如在目標檢測中小目標容易檢測失敗；
top_num需要限制下限，不得小於0，不設上限，可以接受算法返回的所有結果；
閾值根據格式確定，可以是0-100，可以是0-1；
注：為了保證算法效果，有時算法會默認設置參數，即用戶設置的閾值低於默認參數，則不接受輸入，采用默認，用戶是無感知的；
2. 出參
調用接口會有返回信息。產品經理需要根據業務需求定義返回的核心字段信息。
以百度AI開放平台手勢識別為例，跟業務需求相關的關鍵字段包括：
result_num、result，即一張圖片中識別的手勢結果數量，和具體的手勢信息；
result為json數組，包括手勢的類別、手勢檢測框的位置信息【一般識別類算法底層是檢測+識別兩步】、和手勢類別的置信度；
其中result中的一些字段信息，產品可以根據業務需求進行增減，比如目標檢測框的位置信息，一般業務不需要就可以省略。
