後端工程師的工作之一便是規劃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到實作的心得，這篇記錄將來還會持續更新，讓每次的工作都能更順利。