from------------------jackfrued

網(wǎng)絡(luò)API接口設(shè)計

手機App以及使用了Ajax技術(shù)或做了前后端分離的頁面都需要通過網(wǎng)絡(luò)API（Application Programming Interface）和后臺進行交互，所謂API，指的應(yīng)用程序的編程接口；而網(wǎng)絡(luò)API通暢指的是基于HTTP或HTTPS協(xié)議的一個URL（統(tǒng)一資源定位符）幕庐，通過這個URL我們可以讓服務(wù)器對某個資源進行操作并返回操作的結(jié)果闸餐〈衙螅基于HTTP(S)協(xié)議最大的好處就在于訪問起來非常的簡單方便，而且沒有編程語言和應(yīng)用環(huán)境上的差別械哟。

設(shè)計原則

關(guān)鍵問題

為移動端或者PC端設(shè)計網(wǎng)絡(luò)API接口一個非常重要的原則是：根據(jù)業(yè)務(wù)實體而不是用戶界面或操作來設(shè)計恶复。如果API接口的設(shè)計是根據(jù)用戶的操作或者界面上的功能設(shè)置來設(shè)計怜森，隨著需求的變更，用戶界面也會進行調(diào)整寂玲，需要的數(shù)據(jù)也在發(fā)生變化，那么后端開發(fā)者就要不停的調(diào)整API梗摇，或者給一個API設(shè)計出多個版本拓哟，這些都會使項目的開發(fā)和維護成本增加。

下面是某個網(wǎng)站開放API的接口伶授，可以看出API的設(shè)計是圍繞業(yè)務(wù)實體來進行的断序，而且都做到了“見名知意”。

注意：上面的API接口并不是REST風(fēng)格的糜烹，關(guān)于REST的知識违诗，可以閱讀阮一峰老師的《理解RESTful架構(gòu)》以及《RESTful API設(shè)計指南》。

API接口返回的數(shù)據(jù)通常都是JSON或XML格式疮蹦，我們這里不討論后者诸迟。對于JSON格式的數(shù)據(jù)，我們需要做到不要返回null這的值愕乎，因為這樣的值一旦處置失當(dāng)阵苇，會給移動端的開發(fā)帶來麻煩（移動端可能使用強類型語言）。要解決這個問題可以從源頭入手感论，在設(shè)計數(shù)據(jù)庫的時候绅项，盡量給每個字段都加上“not null”約束或者設(shè)置合理的默認值約束。

其他問題

1. 更新提示問題：設(shè)計一個每次使用系統(tǒng)首先要訪問的API比肄，該API會向移動端返回系統(tǒng)更新的相關(guān)信息快耿，這樣就可以提升用戶更新App了。
2. 版本升級問題：API版本升級時應(yīng)該考慮對低版本的兼容芳绩，同時要讓新版本和舊版本都能夠被訪問掀亥，可以在URL中包含版本信息或者在將版本號放在HTTP(S)協(xié)議頭部，關(guān)于這個問題有很多的爭論妥色，有興趣的可以看看stack overflow上面對這個問題的討論铺浇。
3. 圖片尺寸問題：移動端對于一張圖片可能需要不同的尺寸，可以在獲取圖片時傳入尺寸參數(shù)并獲取對應(yīng)的資源；更好的做法是直接使用云存儲或CDN（直接提供了圖片縮放的功能）鳍侣，這樣可以加速對資源的訪問丁稀。

文檔撰寫

下面以設(shè)計評論接口為例，簡單說明接口文檔應(yīng)該如何撰寫倚聚。

評論接口

全局返回狀態(tài)碼

1. GET /comments/{article-id}

   開發(fā)者：王大錘

   最后更新時間：2018年8月10日

   標(biāo)簽：v 1.0

   接口說明：獲取指定文章的所有評論

   使用幫助：默認返回20條數(shù)據(jù)线衫，需要在請求頭中設(shè)置身份標(biāo)識（key）

   請求參數(shù)：

   參數(shù)名	類型	是否必填	參數(shù)位置	說明
   page	整數(shù)	否	查詢參數(shù)	頁碼，默認值1
   size	整數(shù)	否	查詢參數(shù)	每次獲取評論數(shù)量（10~100）惑折，默認值20
   key	字符串	是	請求頭	用戶的身份標(biāo)識

   響應(yīng)信息：

   {
       "code": 10000,
       "message": "獲取評論成功",
       "page": 1,
       "size": 10,
       "totalPage": 35,
       "contents": [
           {
               "userId": 1700095,
               "nickname": "王大錘",
               "pubDate": "2018年7月31日",
               "content": "小編是不是有病呀",
               /* ... */
           },
           {
            "userId", 1995322,
               "nickname": "白元芳",
               "pubDate": "2018年8月2日",
               "content": "樓上說得好",
               /* ... */
           }
       ]
       /* ... */
   }
   

2. POST /comments/{article-id}

   開發(fā)者：王大錘

   最后更新時間：2018年8月10日

   標(biāo)簽：v 1.0

   接口說明：為指定的文章創(chuàng)建評論

   使用幫助：暫無

   請求參數(shù)：

   參數(shù)名	類型	是否必填	參數(shù)位置	說明
   userId	字符串	是	消息體	用戶ID
   key	字符串	是	請求頭	用戶的令牌
   content	字符串	是	消息體	評論的內(nèi)容

   響應(yīng)信息：

   {
       "code": 10001,
       "message": "創(chuàng)建評論成功",
       "comment": {
           "pubDate": "2018年7月31日",
           "content": "小編是不是有病呀"
           /* ... */
       }
       /* ... */
   }