實務上,RESTful API 的 Best Practice
Published in
26 min readAug 14, 2022
此篇原文為:
將 RESTful API 在實務上提到的各種面向,都做了許多分享與說明,此篇主要為翻譯與節錄其中內容,並重新歸納編排,希望能幫助讀者設計出更棒的 RESTful API。
大綱
- 使用設計
- 常見功能
- 資料格式
- Response
第一章: 使用設計
API 必備需求
- 應該合理的去滿足學術上的 Web 標準
- 開發者友善,且能在瀏覽器的網址列上做探索
- 簡單、直覺且具有一致性,能愉悅的去使用
- 具備足夠的彈性
- 在不同需求的維護間,能保持一定的效率
API 就是開發者的 UI,因此 API 的使用者體驗,也是非常重要的。
使用 RESTful URLs 和 actions 命名資源
- 怎麼操作資源
如果有一個做法得到了廣泛的採用,那就會是 RESTful 原則。這些是由 Roy Fielding 在他 network based software architectures 的論文中有介紹到的。
REST 最關鍵的原則就是要把 API 分配到不同的資源上,並且使用不同的 HTTP method 去操作 (GET, POST, PUT, PATCH, DELETE)。
而在資源的命名上,應是以名詞命名,而不是動詞。
而在外部資源和內部資料模型的媒合上,不一定是 1:1 的關係。資源的命名應該要以 API 使用者的角度出發。例如外部使用 ticket
的資源,對應到內部的 ExternalTicket
和…