日常產品開發過程中，涉及前後端數據交互的時候，往往會離不開接口調用，儘管產品經理一般不需要寫接口文檔（負責接口中間層產品經理除外），但對接口瞭解，對於需求溝通、需求傳達還是很有幫助的。
接口是什麼？
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中的一些字段信息，產品可以根據業務需求進行增減，比如目標檢測框的位置信息，一般業務不需要就可以省略。
