簡介

? ?　一種軟件架構風格、設計風格，而不是標準，只是提供了一組設計原則和約束條件。它主要用于客戶端和服務器交互類的軟件。基于這個風格設計的軟件可以更簡潔，更有層次，更易于實現緩存等機制。

　　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占用率大，等等

返回結果

• • GET /collections 返回資源列表
  • GET /collections/:id 返回單獨的資源
  • POST /collections 返回新生成的資源對象
  • PUT /collections/:id 返回完整的資源對象
  • PATCH /collections/:id 返回被修改的屬性
  • DELETE /collections/:id 返回一個空文檔

優秀資源博主：

RESTful介紹和使用教程

優秀資源博主：

RESTful 詳解

?

轉載于:https://www.cnblogs.com/2019wxw/p/10903436.html

總結

以上是生活随笔為你收集整理的初识 RESTful API规范的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。