後端工程師的工作之一便是規劃API,不論是公司內部提供給前端或是第三方的溝通。這篇文章整設計API前要注意的事項
在API設計之前
提供給前端的API請先和前端工程師及UI/UX 討論流程和需要的功能。一般來說,UI/UX會先出圖,再來才是前後端工程師討論,此時要從用戶(前端和UI/UX)的角度思考:
- 為什麼他們需要這個功能
- 此功能要完成什麼工作,如果讓後端邏輯變複雜,有沒有其它替代方案?
- 之後會不會擴展API功能(如增加第三方支付廠商,或是為其它客戶做客製化)
這個階段得具體和詳細的討論,在流程和功能沒結果前不動手寫code
如果此API只是單純後端的需要,那只是討論的對象不同,其思考方式一樣。
API設計
與用戶討論完API的功能後,下一步就要設計介面
這篇文章談到Restful API在設計需注意的事。先分清楚此API是跟資源有關還是utility的功能,這會影響到URI的設計
跟資源相關的就是CRUD操作,例如註冊會員或刪除文章
而utility的API可能不特別針對哪個資源,例如 background job
至於使用哪個http動詞就看該行為了,例如註冊一個會員帳號你可能會使用 POST /1/members
一切先以用戶的角度看待介面的合理性。
設計時需要針對各操作構思後端的邏輯,列出該操作所有的選項,思考使用的DB資源,此時對於整個API應該有清楚的規劃。
API實作之前
在API實作之前還需要
- 寫unit test
- 撰寫API文件,讓前端人員參考
單元測試有幾點須注意:
- 測試應涵蓋設計階段討論的 corner case
- 測試資料應盡可能簡明
- API上線後如果遇到當初沒討論的狀況,先寫測試再解bug
在撰寫文件方面,我們團隊使用API Doc幫助產出document。不用另外存放文件,用註解的方式就能產出文件,對於前後端人員都是很方便的作法。
以上是這陣子和同事討論API到實作的心得,這篇記錄將來還會持續更新,讓每次的工作都能更順利。