對於專案的開發和維護，私以為一致性是最重要的因素之一，甚至比一段牛逼的演算法更能影響一個專案的成敗。
一致性之於REST API的設計，那更是關鍵。無需追求最優方案，但希望大家API能夠保持一致。

先上例子

1. Get /v1/users #獲取所有使用者
2. Get /v1/users/1 #獲取id為1的使用者資訊(記得返回值去掉敏感資訊)
3. Get /v1/users?departmentId=1 #獲取部門id為1的使用者
4. Get /v1/users?offset=0&limit=20 #分頁獲取20個使用者
5. GET /v1/users/1/orders #獲取id為1的使用者擁有的訂單
6. POST /v1/users #新建一個使用者
7. PUT /v1/users/1 #修改id為1的使用者資訊
8. DELETE /v1/users/1 #刪除id為1的使用者

下面列出幾條建議：

1. 永遠攜帶版本號
   REST API是永久約定，不能修改，只能新增版本，所以從開始就考慮版本問題。

2. GET方法不允許修改資料
   HTTP約定GET方法不改變狀態，可以對GET請求進行快取處理。

3. 保證PUT請求的冪等性
   PUT與POST請求的差別就在於PUT是冪等的。冪等我的理解很簡單，多次請求保證最多正常處理一次。
   無需冪等的，用POST。

4. 文件文件文件
   在公共地方(如wiki)留下文件，使得API呼叫者可以隨時檢視對應文件。

5. url主體部分字母全部小寫
   paremeter部分用駝峰表示，如departmentId。