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

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

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

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

話不多說，直接進(jìn)入主題

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

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

步驟

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

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

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

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

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

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

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

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

同樣也分為兩部分：

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

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

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

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

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

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

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

小結(jié)

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

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

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