簡單的網絡api接口設計

網絡API接口設計

手機App以及使用了Ajax技術或作了先後端分離的頁面都須要經過網絡API（Application Programming Interface）和後臺進行交互，所謂API，指的應用程序的編程接口；而網絡API通暢指的是基於HTTP或HTTPS協議的一個URL（統一資源定位符），經過這個URL咱們可讓服務器對某個資源進行操做並返回操做的結果。基於HTTP(S)協議最大的好處就在於訪問起來很是的簡單方便，並且沒有編程語言和應用環境上的差異。

設計原則

關鍵問題

爲移動端或者PC端設計網絡API接口一個很是重要的原則是：根據業務實體而不是用戶界面或操做來設計。若是API接口的設計是根據用戶的操做或者界面上的功能設置來設計，隨着需求的變動，用戶界面也會進行調整，須要的數據也在發生變化，那麼後端開發者就要不停的調整API，或者給一個API設計出多個版本，這些都會使項目的開發和維護成本增長。

下面是某個網站開放API的接口，能夠看出API的設計是圍繞業務實體來進行的，並且都作到了「見名知意」。

評論
comments/show	獲取某條微博的評論列表
comments/by_me	本身的評論列表
comments/to_me	收到的評論列表
comments/mentions	@了本身的評論列表
comments/create	建立一條評論
comments/delete	刪除一條評論
comments/reply	回覆一條評論

注意：上面的API接口並非REST風格的，關於REST的知識，能夠閱讀阮一峯老師的《理解RESTful架構》以及《RESTful API設計指南》。

API接口返回的數據一般都是JSON或XML格式，咱們這裏不討論後者。對於JSON格式的數據，咱們須要作到不要返回null這的值，由於這樣的值一旦處置失當，會給移動端的開發帶來麻煩（移動端可能使用強類型語言）。要解決這個問題能夠從源頭入手，在設計數據庫的時候，儘可能給每一個字段都加上「not null」約束或者設置合理的默認值約束。

其餘問題

1. 更新提示問題：設計一個每次使用系統首先要訪問的API，該API會向移動端返回系統更新的相關信息，這樣就能夠提高用戶更新App了。
2. 版本升級問題：API版本升級時應該考慮對低版本的兼容，同時要讓新版本和舊版本都可以被訪問，能夠在URL中包含版本信息或者在將版本號放在HTTP(S)協議頭部，關於這個問題有不少的爭論，有興趣的能夠看看stack overflow上面對這個問題的討論。
3. 圖片尺寸問題：移動端對於一張圖片可能須要不一樣的尺寸，能夠在獲取圖片時傳入尺寸參數並獲取對應的資源；更好的作法是直接使用雲存儲或CDN（直接提供了圖片縮放的功能），這樣能夠加速對資源的訪問。

文檔撰寫

下面以設計評論接口爲例，簡單說明接口文檔應該如何撰寫。

評論接口

全局返回狀態碼

返回碼	返回信息	說明
10000	獲取評論成功
10001	建立評論成功
10002	沒法建立評論	建立評論時因違反審覈機制而沒法建立
10003	評論已被刪除	查看評論時評論因不和諧因素已被刪除
10004	……	……

1. GET /comments/{article-id}

   開發者：王大錘

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

   標籤：v 1.0

   接口說明：獲取指定文章的全部評論

   使用幫助：默認返回20條數據，須要在請求頭中設置身份標識（key）

   請求參數：

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

   響應信息：

   {
       "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}

   開發者：王大錘

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

   標籤：v 1.0

   接口說明：爲指定的文章建立評論

   使用幫助：暫無

   請求參數：

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

   響應信息：

   {
       "code": 10001,
       "message": "建立評論成功",
       "comment": {
           "pubDate": "2018年7月31日",
           "content": "小編是否是有病呀"
           /* ... */
       }
       /* ... */
   }