RESTful

RESTful 是一種系統開發設計風格、原則。可視情況調整，以下參考來源 RFC5789 (https://tools.ietf.org/html/rfc5789)。

Noun

• 一般資源

​ 通用於一律使用複數名詞

​ 例如：/books 或 /books/123。但有部分人認為應該使用單數名詞，因為： /book/123 看似比 /books/123 合理。但想想檔案 系統的目錄命名 (例如/Users或/Documents)，其實用複數也沒問題。複數可以保持API endpoint的一致性，所以一般資源建議用複數。

• 唯一資源：對 client 而言只有一份的資源

​ 通用於單數名詞

​ 例如：user 是指目前驗證的使用者，使用者永遠只能同時登入一個使用者

Http Method

• Safe：該操作不會改變伺服器端的資源狀態 (而且結果可以被cache)，屬於 Safe 的操作必定屬於 Idempotent
• Idempotent (冪等性)：該操作不管做1遍或做n遍，都會得到同樣的資源狀態結果 (但不一定得到同樣的回傳值，例如第2次DELETE請求可能回傳404)，因此client端可以放心retry

GET

• SAFE：每次執行操作時，GET 只有讀取 Resource，不會改變到任何的 Resource (資源, 資料)
• Idempotent：每次執行操作時，GET 只有讀取 Resource，不會改變到任何的 Resource (資源, 資料)，所以任何資源的任何狀態都是一樣的

POST

• 每次執行操作時，POST 都會建立一個 Resource (資源, 資料)
• 範例：建立使用者
  • 執行第一次時：建立一個 name = “帥小慶” 的 user，但其 id = 1
  • 執行第二次時：建立一個 name = “帥小慶” 的 user，但其 id = 2，發送同樣的請求，可每次都是不同的 Resource

  POST /users
  Data:
    {
      "name": "帥小慶"
    }

• Create：建立一個可以完全獨立存在的實體
• 範例：建立使用者 ​ 建立使用者前不需要建立任何的東西，就可以建立使用者了，使用者是可以完全獨立的存在

POST /users
Data:
  {
    "name": "帥小慶"
  }

• Add：增加一個必須依賴於某個實體的實體 ​ 資料結構：1對多的關係
• 範例：Add a public key on behalf of a user 增加一個代表使用者的公鑰 (Gitea API) ​ 增加這個公鑰之前，使用者必須存在，公鑰必須歸屬於某個使用者之下 ​ 公鑰跟姓名一樣，使用相同電腦的公鑰就會相同，但不表示是同一個使用者，故公鑰也會有自己的 ID ​ 我每次增加公鑰時，都將生成不同的公鑰 ID

  POST/admin/users/{username}/keys

PUT

• Idempotent：每次執行操作時，PUT 都會取代 Resource，不管操作幾次，使用者獲取得 Resource 結果都是一樣的
• Replace：不論資源如何，最終的資源狀態都是一樣的 ​ Resource 已存在時，或許不理會、或許先刪除後建立 (取代) ​ Resource 不存在時，直接建立
• Add：添加唯一關係，建立這個唯一關係前，兩個關連實體都必須存在。在沒有建立關係前，兩個關連實體都可以互相獨立存在
• 資料結構應為：多對多，且兩個關連實體的 PK，同時也是關係實體的 PK、FK
• 範例：增加使用者與角色的關係 ​ 增加使用者跟角色的關係前，使用者跟角色都必須存在；增加使用者跟角色的關係前，使用者跟角色可以獨立存在 ​ 使用者 23240，跟角色 2，的關係最多只能有一條關係 (使用者 23240 有角色 2 )，最少沒有關係 (使用者 23240 沒有角色 2 ) ​ 執行第二次操作時，使用者 23240 跟角色 2 的從屬關係仍然存在，也不會跑出第二條使用者 23240 跟角色 2 的從屬關係

  PUT user/{account}/roles
  Data
    {
      "role_id": "2"
    }

• 範例：Follow a user 關注一個使用者 (Gitea) ​ 增加關注關係時，關注者與被關注者 (都是使用者) 都必須存在；增加關注關係時，關注者與被關注者 (都是使用者) 都必須存在 ​ 關注者使用者 23240，跟被關注者使用者 F3860056，的關係最多只能有一條關係 (23240 關注 F3860056)，最少沒有關係 (23240 不關注 F3860056) ​ 執行第二次操作時，關注者 23240 跟被關注者 F3860056 的關注關係仍然存在，也不會跑出第二條關注者 23240 跟被關注者 F3860056 的關注關係

  PUT/user/following/{username}

#### PATCH

• Edit：編輯可獨立存在、且已經存在的實體，也就是產生新版本的實體，可能會影響其他 Resource
• 範例：編輯使用者 ​ 編輯使用者，使用者已經存在，且我們可能有紀錄編輯時間、編輯人、編輯IP，所以每次的編輯都會造成不一樣的結果 ​ 第一次編輯使用者，更新時間變為 08:00，編輯人 23240，IP 10.151.110.165 ​ 第二次編輯使用者，更新時間變為 09:00，編輯人 23241，IP 10.151.110.144

  PATCH /users/{account}

DELETE

• Idempotent：每次執行操作時，DELETE 都會刪除相同的東西
• 範例：刪除使用者 ​ 第一次刪除使用者23240，刪除使用者23240 ​ 第二次刪除使用者23240，還是刪除使用者23240，只不過使用者 23240 不存在了

  DELETE /users/{account}

HTTP Status Code

HTTP状态码（HTTP Status Code）是用以表示网页服务器HTTP响应状态的3位数字代码。所有状态码的第一个数字代表了响应的五种状态之一。 除非另有说明，状态码是HTTP / 1.1标准（RFC 7231）的一部分。

而关于 RESTful API 的请求状态，通常有以下两种设计方案：

• 方案一：使用 HTTP 状态码来表示请求状态，200 时返回的内容就是数据；
• 方案二：所有接口都返回 200 ，在响应内容里约定 错误码 或 錯誤信息

在實際應用中，應據具體情景及需要進行選擇與調整。

常用HTTP狀態碼