編輯導(dǎo)讀：產(chǎn)品經(jīng)理在工作中，避免不了要閱讀接口文檔，但是有很多新人產(chǎn)品對接口并不太了解。本文作者分享了接口文檔從0到1的過程，從業(yè)務(wù)、產(chǎn)品層面闡述了接口文檔的結(jié)構(gòu)及內(nèi)容的規(guī)范，希望對你有所幫助。

前兩天接到領(lǐng)導(dǎo)的一個任務(wù)，讓我根據(jù)業(yè)務(wù)流程圖設(shè)計出一份接口交互文檔出來；

此時小白的內(nèi)心就有點慌，不知道要怎么開始……

經(jīng)過一番冷靜思考后，我翻出了之前參加過幾個項目的接口文檔及業(yè)務(wù)流程圖；然后參考之前文檔照葫蘆畫瓢，結(jié)合自己的經(jīng)驗理清了本次接口設(shè)計的思路及主體框架形成初步方案；再帶著我的初步方案找領(lǐng)導(dǎo)確認；經(jīng)過領(lǐng)導(dǎo)的一番耐心指導(dǎo)，確定了此次接口文檔的框架及要點；就這樣屁顛屁顛回去開搞了。

話不多說，直接進入主題

下圖是經(jīng)過抽象簡化脫敏后的業(yè)務(wù)流程圖，涵蓋了融資的主要過程：

材料提交、材料審核、授信、借款申請、放款審核、放款、還款、逾期處理等。另外根據(jù)不同資金方，流程圖中列舉了一些不同點，希望對大家的工作有所啟發(fā)。

步驟

在我看來接口設(shè)計主要分為2步：確定接口交互節(jié)點和規(guī)范接口內(nèi)容

第一步是確定接口交互節(jié)點

確定交互節(jié)點主要分為兩部分：

1. 與業(yè)務(wù)流程強關(guān)的，時效性要求比較高的接口。如準(zhǔn)入結(jié)果查詢、資方額度查詢等；
2. 與業(yè)務(wù)主流程不那么相關(guān)的，時效性要求不高的。如貸中監(jiān)控數(shù)據(jù)推送、還款跑批，逾期代償?shù)龋?/li>

先將整個流程分為四大部分：材料提交、授信、借款、還款（含逾期代償）；

然后結(jié)合業(yè)務(wù)路程圖，按照在什么階段、什么場景、觸發(fā)關(guān)鍵節(jié)點的前置條件，交互的方向以及時效性，梳理出交互節(jié)點。如下圖例子：

再梳理出時效性要求不高的那部分，格式與上面的保持一致。不過，這部分一般比較散亂，需要具備一定的經(jīng)驗才能考慮周全；我的做法是取所有項目接口的并集，然后根據(jù)項目情況刪除一些用不到的。這樣子第一步就完成了。

第二步是規(guī)范接口內(nèi)容

同樣也分為兩部分：

1. 確認請求和響應(yīng)要傳輸?shù)臄?shù)據(jù)；
2. 對傳輸數(shù)據(jù)類型進行定義；

這部分我僅從業(yè)務(wù)、產(chǎn)品層面思考。

1. 每一個接口中都存在唯一的標(biāo)識碼（我猜應(yīng)該是銀行用于區(qū)分是哪項業(yè)務(wù)）；
2. 根據(jù)所處的業(yè)務(wù)階段，傳輸不同的字段。如授信接口，傳姓名、身份證、手機號、銀行卡等等；

接下來就是對請求、響應(yīng)接口它的參數(shù)名稱、出現(xiàn)要求、示例值、備注規(guī)定好，其他的如：字段長度、類型就交給研發(fā)了；

• 參數(shù)名稱：一般是漢語轉(zhuǎn)英語，如用戶編號，UserID；
• 出現(xiàn)要求：主要有必須出現(xiàn)M、條件出現(xiàn)C、選擇出現(xiàn)O三種；
• 示例值：如UserName：張三；

備注：對某些可能存在歧義或者有特殊規(guī)定的進一步說明；如ApprovalStatus，授信通過情況，01通過，02拒絕；

全部完成后，就是對這些接口匯總，生成目錄，形成文檔。最后就可以交差啦！

小結(jié)

簡單來說，接口設(shè)計主要就是確定交互節(jié)點和規(guī)范接口內(nèi)容；先根據(jù)業(yè)務(wù)流程梳理出交互節(jié)點，再深刻理解業(yè)務(wù)背景對接口進行詳細定義；

本文由 @九牧 原創(chuàng)發(fā)布于人人都是產(chǎn)品經(jīng)理。未經(jīng)許可，禁止轉(zhuǎn)載

題圖來自Unsplash，基于CC0協(xié)議