起點課堂會員權益
職業體系課特權
線下行業大會特權
個人IP打造特權
30+門專項技能課
1300+專題課程
12場職場軟技能直播
12場求職輔導直播
12場專業技能直播
會員專屬社群
榮耀標識4個要點，編寫一份接口需求文檔
在產品設計工作中，或多或少都會需要用到接口，特別是業務導向性的系統，接口幾乎是必不可少的功能。那么什么是接口？如何寫一份能準確表達業務需求的接口需求文檔呢？
一、什么是接口
百科上對接口的定義：API（Application Programming Interface,應用程序編程接口）是一些預先定義的函數，目的是提供應用程序與開發人員基于某軟件或硬件得以訪問一組例程的能力，而又無需訪問源碼，或理解內部工作機制的細節。
要理解接口是什么，首先理解一下為什么要用接口？
兩個獨立的系統，它們的數據或程序是獨立的，這就使得它們無法直接訪問對方的數據庫或程序（兩個獨立的數據相當于兩個獨立的家庭，每個家庭肯定是不允許外人隨便進入的，否則會發生偷竊等后果嚴重的事件）。但是某些業務場景下，獨立的系統之間又必須相互共享數據或共用一套程序邏輯，如統一業務流程上的不同業務操作系統，下游系統的業務依賴于上游系統的數據。
既然如此為什么不把它們設計成一個系統，這樣不就沒有上面的問題了嗎？
這是因為有的業務流程很長很復雜，如果設計成一個系統，整個系統變得很龐雜，不論是功能設計、開發維護都很難。因此一般都會把雖然有上下游業務關系但又有清晰邊界的業務劃分成獨立的系統實現，如采購系統和倉儲系統。此外，很多時候我們需要獲取的數據是我們外部其他公司擁有的數據，更不可能設計成同一個系統了。
基于以上兩點：接口就是兩個獨立系統之間同步數據或訪問對方程序的途徑。
二、如何設計接口
1. 搞清楚是主動訪問還是被動請求：
a. 若是主動訪問，有兩種情況：
一是我方是數據的使用方，需要主動從對方獲取數據；二是我方是數據的提供方，需要主動將數據同步給對方。
主動訪問時無需做接口，而是訪問對方的接口，要搞清楚的問題是：我們需要在什么節點訪問對方的接口？是用戶觸發某個操作的時候實時去訪問？還是沒有實時性要求，只是周期性地訪問？
若我方是數據的使用方且需要的數據是用戶使用某個功能必須的數據，因此必須在用戶操作時實時去訪問對方的接口獲取數據并展示給用戶，典型的有我們注冊某網站時獲取驗證碼的功能。
若我方是數據的使用方且需要的數據是一些跟用戶實時操作無關的基礎數據，如客服系統需要從其他業務系統獲取用戶的基礎數據，以在系統中的某些功能下展示用戶的信息（如客服在處理客訴等問題時，需要知道客戶的一些詳細信息，這些信息只有業務系統有）。這種情況下，一般會新增一個腳本定時（如兩小時一次）訪問對方的接口將數據獲取過來存儲到自己的數據庫，在用到的時候直接從自己數據庫獲取并展示。
若我方是數據的提供方且提供的數據是下游系統需要的實時要求高的數據則更多地用實時同步；若是基礎數據，則選擇周期性同步的方式。
b. 若是被動請求，有兩種情況：
一是我方是數據提供方，需要對方來獲取數據；二是我方是數據使用方，需要對方主動將數據同步過來。
被動請求需要提供接口供對方訪問，此時要搞清楚：讓對方來訪問的時候，需要提供什么樣的參數？根據他提供的參數我們需要返回什么數據？這些數據從哪里取值？
若有一些數據的來源是本系統，其他系統需要使用這些數據，則可提供接口讓其他系統通過訪問接口獲取這些數據。
若我方是數據使用方且讓對方將數據主動同步過來，此種場景典型如——我們是業務的下游，上游系統產生數據后，需要將數據同步到下游系統讓流程繼續進行，并且流程的及時性要求高，不能有延遲。這種情況下，只有上游系統知道什么節點產生了數據，因此只有等他產生數據后主動推送給下游系統，因為下游系統因無法知道數據生成的時間，也就無法及時去獲取數據，這時最好的方式是讓對方主動將數據同步過來。
2. 搞清楚數據交互的實時性要求
a. 對于我方是數據使用方的情況，要根據業務的需要決定獲取數據的實時性。
如上文所說，如果是用戶使用功能時需要的數據就是即時性訪問。如果是定期獲取基礎數據，根據我們對數據準確性的要求和對方數據變更的頻率決定獲取的周期。如我們對數據的準確性要求不是100%的要求，且對方的數據變更頻率也不是很高，則周期可設計得長一些，如每天一次，每幾個小時一次等。
b. 對于我方是數據提供方的情況，則以對方的業務需要為準，但是對于獲取數據的訪問量大等特殊情況，應在需求中或評審中做好說明和交代，以幫助開發設計更滿足需要的接口。
3. 選擇合適的接口方式
結合接口的不同類型和實時性要求兩方面，可以選擇合適的接口實現方式：
a. mq消息隊列
是一個中間件，數據提供方將數據放到中間件，數據獲取方從中間件中獲取數據。針對向多個系統同步基礎數據的需要，消息隊列是最適合的方式。
若選擇這種同步方式，要注意的一點是：增量同步還是全量同步，若是增量同步，對方是增量獲取還是全量獲?。咳羰侨客?，在什么情況下，對方應該更新數據，什么情況下應該更新數據？
b. otter同步
數據同步方直接訪問數據獲取方的數據表將數據寫入對應的表中，這種方式實時性最高，若對數據的準確性要求很高，此方式是很好的數據同步方式。
c. http
一般在功能設計中常用的接口是此種方式，雙方通過http地址保持數據同步和通信。
在設計具體的數據同步接口時，具體的方式產品經理不用關注，由開發根據需求設計合理的方式，然后產品可幫助開發一起確定所選方式是否滿足業務需要。除非業務上有特殊要求，則在需求中可指定具體的方式。
三、如何編寫接口文檔
不同的接口使用場景，需要關注的點和交代清楚的規則不一樣，以主動/被動+數據使用方/數據獲取方的維度，有以下四種情況：
1. 如果是向對方系統主動推送數據，則可按以下方式整理接口需求
2. 如果是對方主動來獲取數據，則可按以下方式整理接口需求
3. 如果是被動接收對方推送的數據，則可按以下方式整理接口需求
4. 如果主動從對方獲取數據，則可按以下方式整理接口需求
PS：在下一篇文章中將以具體的文檔實例來說明不同的場景應該考慮和注意的點。書寫過程中一些偏技術的點應及時與開發咨詢和溝通，防止編寫的文檔與實際出入太大；接口的開發肯定涉及兩個系統，因此在評審前與對方產品對好文檔是必須的，要保證雙方開發拿到的文檔標準是一樣的，否則在開發過程中會出現雙方約定不一致導致需要修改的情況。
#專欄作家#
果果，人人都是產品經理專欄作家。擅長業務導向性的產品設計，以及對業務流程的梳理和復雜問題的拆解，希望能找到產品工作的操作指南和方法論，不斷搭建自己的知識體系
本文原創發布于人人都是產品經理。未經許可，禁止轉載
題圖來自Unsplash, 基于CC0協議
能在里面加一下示例就更棒了。謝謝
返回參數是不是只是系統記錄一下，不會在頁面展示吧
這個看實際的業務需要，有一些信息是關鍵的業務信息，肯定是要解析轉化后展示在界面上的
明白這是給開發的需求文檔，另外想問 對外的專業接口文檔 也是產品來寫嗎？有沒有什么標準的參考模板？thx
對外的專業文檔還是由開發來寫比較好，因為里面要包含實例的；你可以到阿里或騰訊的開放平臺看看，上面有很多開放的API接口文檔，對外專業的就是那種的
JSON實例怎么寫呢，比如JSON列表這種怎么表達報文？？？
這種就讓開發寫，產品不寫這個 哈哈哈
我在迭代的時候會寫。列個表格，包括字段、字段屬性和定義，著重說明想去掉哪些字段增加哪些字段和原因就行。
需求期間就著重寫場景，當輸入什么時返回什么也要列表說清。
接手以前的老接口與主干接口時，需要明白用了哪些接口標準與協議，在對應接口使用處標明，需要有接口本身介紹，錯誤編碼和示例。
但我問了其他產品朋友，有些都不需要寫接口需求，大概每種產品經理都不一樣吧。
謝謝麻雀，寫的很好！
謝謝肯定~~
您好，想請教下：
1.這個表格對于簡單的接口會比較容易寫，但是對于里面多個json格式的要怎么寫呢？
2.一般在寫對外的接口文檔中，我們經常要列【序號、字段英文名、字段中文名、是否必填、類型】等；您提供的表格是不是用于產品經理向開發提需求的時候用的，而不是開發對外提供的接口文檔？
3.感覺【字段來源】、【邏輯驗證規則】提供了新思路，謝謝分享~
是的 我這個只是產品給開發的接口需求描述文檔，不是向外介紹接口的專業接口文檔
json格式的我理解應該是有主信息和明細信息區分，可以再分一列來交代是主信息，包含哪些明細
專業開放接口的文檔還是要參考一些開放平臺上的說明，除了文檔外要加上實例，你可以參考騰訊云、阿里云這些開放平臺上的接口看看
好的，謝謝~
您好，請問向對方系統推送數據時，是對方系統調用我方接口嗎？；被動接收對方推送的數據時，是我方調用對方接口嗎？
向對方系統推送數據時：是咱們訪問對方的接口，將數據推給他
被動接收對方推送的數據時：是對方訪問咱們的接口把數據推過來
你剛好理解反了 ??
現在明白了，誰主動誰就去調誰的接口 ??
誰被動誰給接口
是的
增量同步還是全量同步，若是增量同步，對方是增量獲取還是全量獲取？若是全量同步，在什么情況下，對方應該更新數據，什么情況下應該更新數據？
————————————–
增量同步和全量同步是不是貼重復了，可以再解釋一下嗎，不太懂這兩個的區別，以及產品經理要明確什么，想學習一下，謝啦
增量的意思就是：持續同步新產生的數據，即每次只同步截止上次同步產生的新數據
全量的意思就是：每次都把所有的數據都同步過去，不管是否已經同步過了
增量接收的意思就是：對方每次接收到數據后按新數據對待，將接收的數據插入到數據庫中
全量接收的意思就是：對方每次接收到數據后全量更新之前的數據（以一定的唯一維度更新），若已有數據中沒有的時候才插入新數據
這一塊產品只需要作為一個考量因素，具體方案可以在出方案的時候跟技術一起商討確定；主要還是看業務上的情況 以及數據的量等因素共同確定
老實說。最后一張表沒看懂。
就是你通過傳參數的方式從對方接口獲取你想要的數據；比如傳輸你的姓名，對方給你返回你的姓名、身份證號、手機號等等
標題行管的到返回參數列碼？比如“傳輸給對方的請求參數”、“狀態”等，也屬于“字段名稱”嗎？還有表2其實也有這個問題。
也算呀 請求參數就是一個個字段的 自然就有字段名稱嘛 狀態本身就是個字段
沒想到你竟然回復了。
感謝分享
??
下周和合作方對接！我好激動！接口文檔產品要寫嗎？需求里應該咋寫
寫需求文檔就行了 按上面的模板寫應該可以 但也要看你們的具體要求
學習了！！期待下一篇的文檔實例！
m
學習了！接口需求沒具體寫過
贊，期待下一篇 ??
寫得好呀。接口文檔可能存在的坑太多了。字段的數據源/冪等處理/不同場景下主鍵的選擇。還有最重要的，在面多多個合作方時，如何說服對方使用自己的標準API。
寫的很好，接口需求在需求文檔里我從來沒寫過，領教了，希望多寫一些這樣的文章
高手啊
1
謝謝~
接口文檔一般不是開發寫嗎？
這是需求文檔哦
您好 請問文章可以轉載嗎？？？
要轉載到哪里呢？
感覺這應該是IT方案需要知道的基本知識，產品只需要知道業務場景需要哪些數據，然后具體實現由SE制定方案
是的 產品就是要交代清楚哪些節點要跟哪個系統進行什么樣的交互 具體交互方式由研發定
MQ中丟了，同步增量還是全量
嗯嗯 是的 增量同步還是全量同步 以及增量消費還是全量消費 都要定義好 不然容易出bug
下一篇什么時候出呢
還不一定哈 工作太忙就比較少時間寫 有問題可以先交流??
謝謝~
多謝關注哦，還不一定啥時候寫完 ?
產品經理如果熟悉架構師的工作，的確增加不少競爭力。
??還有很多東西要學習 現在還只是淺層的認識