rest
是一種軟體架構風格,如果你們的介面是 rest
介面,那麼就可被認為你們的的介面是restful的,英文名詞和形容詞的區別。

rest
介面是圍繞“資源”展開的,利用HTTP的協議,其實rest本也可以和HTTP無關,但是現在大家普遍的使用 rest
都是依託於HTTP協議。HTTP 的url即資源。

RFC 3986
定義了通用的URI語法:

URI = scheme “://” authority “/” path [ “?” query ][ “#” fragment ]
  • scheme: 指底層用的協議,如http、https、ftp
  • host: 伺服器的IP地址或者域名
  • port: 埠,http中預設80
  • path: 訪問資源的路徑,就是咱們各種web 框架中定義的route路由
  • query: 為傳送給伺服器的引數
  • fragment: 錨點,定位到頁面的資源,錨點為資源id

RESTful API設計

資源路徑

對於rest資源的定義,即URL的定義,是最重要的;想要設計出優雅的、易讀的rest 介面,其實還是聽不容易的。

URL中不能有動詞

在Restful架構中,每個網址代表的是一種資源,所以網址中不能有動詞,只能有名詞,動詞由HTTP的 get、post、put、delete 四種方法來表示。

URL結尾不應該包含斜槓“/”

這是作為URL路徑中處理中最重要的規則之一,正斜槓(/)不會增加語義值,且可能導致混淆。REST API不允許一個尾部的斜槓,不應該將它們包含在提供給客戶端的連結的結尾處。

許多Web元件和框架將平等對待以下兩個URI:

http://api.canvas.com/shapes/

http://api.canvas.com/shapes

但是,實際上URI中的每個字元都會計入資源的唯一身份的識別中。

兩個不同的URI對映到兩個不同的資源。如果URI不同,那麼資源也是如此,反之亦然。因此,REST API必須生成和傳遞精確的URI,不能容忍任何的客戶端嘗試不精確的資源定位。

有些API碰到這種情況,可能設計為讓客戶端重定向到相應沒有尾斜槓的URI(也有可能會返回301 - 用來資源重定向)。

正斜槓分隔符”/“必須用來指示層級關係

rul的路徑中的正斜槓“/“字元用於指示資源之間的層次關係。

例如:

http://api.user.com/schools/grades/classes/boys
- 學校中所有的男生

http://api.college.com/students/3248234/courses
- 檢索id為3248234的學生學習的所有課程的清單。

應該使用連字元”-“來提高URL的可讀性,而不是使用下劃線”_”

為了使URL容易讓人們理解,請使用連字元”-“字元來提高長路徑中名稱的可讀性。

一些文字檢視器為了區分強調URI,常常會在URI下加上下劃線。這樣下劃線”_”字元可能被文字檢視器中預設的下劃線部分地遮蔽或完全隱藏。

為避免這種混淆,請使用連字元”-“而不是下劃線

URL路徑中首選小寫字母

RFC 3986將URI定義為區分大小寫,但scheme 和 host components除外。

URL路徑名詞均為複數

為了保證url格式的一致性,建議使用複數形式。

RESTful API對資源的操作

對於rest api資源的操作,由HTTP動詞表示

CURD操作

  • GET: 獲取資源
  • POST: 新建資源
  • PUT:在伺服器更新資源(向客戶端提供改變後的所有資源)
  • PATCH: 在伺服器更新資源(向客戶端提供改變的屬性)
  • DELETE:刪除資源

PATCH
一般不用,用 PUT

資源過濾

在獲取資源的時候,有可能需要獲取某些“過濾”後的資源,例如指定前10行資料

http://api.user.com/schools/grades/classes/boys?page=1&page-size=10

返回狀態碼推薦標準HTTP狀態碼

有很多伺服器將返回狀態碼一直設為200,然後在返回body裡面自定義一些狀態碼來表示伺服器返回結果的狀態碼。由於rest api是直接使用的HTTP協議,所以它的狀態碼也要儘量使用HTTP協議的狀態碼。

  • 200 OK 伺服器返回使用者請求的資料,該操作是冪等的
  • 201 CREATED 新建或者修改資料成功
  • 204 NOT CONTENT 刪除資料成功
  • 400 BAD REQUEST 使用者發出的請求有問題,該操作是冪等的
  • 401 Unauthoried 表示使用者沒有認證,無法進行操作
  • 403 Forbidden 使用者訪問是被禁止的
  • 422 Unprocesable Entity 當建立一個物件時,發生一個驗證錯誤
  • 500 INTERNAL SERVER ERROR 伺服器內部錯誤,使用者將無法判斷髮出的請求是否成功
  • 503 Service Unavailable 服務不可用狀態,多半是因為伺服器問題,例如CPU佔用率大,等等

轉載:https://www.colabug.com/228298.html