實務上，RESTful API 的 Best Practice

Source: https://unsplash.com/photos/L9QoKLSCBNs

此篇原文為:

Best Practices for Designing a Pragmatic RESTful API

將 RESTful API 在實務上提到的各種面向，都做了許多分享與說明，此篇主要為翻譯與節錄其中內容，並重新歸納編排，希望能幫助讀者設計出更棒的 RESTful API。

大綱

1. 使用設計
2. 常見功能
3. 資料格式
4. Response

第一章: 使用設計

API 必備需求

• 應該合理的去滿足學術上的 Web 標準
• 開發者友善，且能在瀏覽器的網址列上做探索
• 簡單、直覺且具有一致性，能愉悅的去使用
• 具備足夠的彈性
• 在不同需求的維護間，能保持一定的效率

API 就是開發者的 UI，因此 API 的使用者體驗，也是非常重要的。

使用 RESTful URLs 和 actions 命名資源

1. 怎麼操作資源

如果有一個做法得到了廣泛的採用，那就會是 RESTful 原則。這些是由 Roy Fielding 在他 network based software architectures 的論文中有介紹到的。

REST 最關鍵的原則就是要把 API 分配到不同的資源上，並且使用不同的 HTTP method 去操作 (GET, POST, PUT, PATCH, DELETE)。

而在資源的命名上，應是以名詞命名，而不是動詞。

而在外部資源和內部資料模型的媒合上，不一定是 1:1 的關係。資源的命名應該要以 API 使用者的角度出發。例如外部使用 ticket 的資源，對應到內部的 ExternalTicket 和…