iT邦幫忙

第 12 屆 iThome 鐵人賽

DAY 18
1
Modern Web

30天從零撰寫 Kotlin 語言並應用於 Spring Boot 開發系列 第 18

[Day 18] 遠征 Kotlin × Spring Boot 使用 RESTful API (1)

  • 分享至 

  • xImage
  •  

前面兩篇我們已經介紹完資料庫操作,可能有朋友會疑問 API 細節是如何進行實現,為什麼我們在 程式中加入 @RestController@GetMapping 就可以實作一個 API 進行呼叫,甚至好奇什麼是 API,這篇將來解釋 API 實作細節並介紹 RESTful API 設計風格。

API 的基本介紹我想可以直接參考這篇文章,作者提到的 API 概念非常清晰,我們整理內容大概描述,應用程式介面(Application Programming Interface, API)是扮演應用程式與應用程式之間溝通的橋樑,以幫助使用者達到目的為目標導向,讓使用者在操作 API 的過程,不需要知道內部程式運作的邏輯,只要告訴 API 你的需求,即可達到目的

而 API 常見設計的風格有 RESTGraphQLgRPCWebhooks,我們在這篇會先提到目前普遍率最高的 RESTful API來介紹。REST 全名為 Representational State Transfer( 表現層狀態轉移),是此段開頭提到的其中一種 API 設計風格,而 RESTful 只是將 REST 轉為形容詞,一般在設計 Restful API 我們會通常會考慮四個重要觀念,如下:

  1. Nouns 名詞

    API Endpoint 必須使用 名詞 進行定義 URL,而每個資源都要保持唯一性,資源採用複數命名,例如學生資料就是 /students

  2. Verbs 動詞

    利用 Verbs 動詞Nouns 名詞 (資源 URL) 進行操作,在 HTTP 1.1 的實作就是 HTTP Method,即 Get、Post、Put、Delete、Patch等,例如使用 Get Method 取得學生資料、用 Delete Method 刪除學生資料,動詞分別描述如下:

    • Get 讀取資源
    • Post 新增替源或作為utility API,例如檢查帳號是否存在
    • Delete 刪除資源
    • Put 替換單一資源
    • Patch 更新資源部份內容
  3. Content Types 資源呈現方式

    當我們如果要取得某一個 API 的資料,此資料格式可以有 HTML、 XML、JSON 等格式,同樣的 URL 資源可以有不同型態的表現方式。

  4. HTTP 回傳狀態碼

    API 回傳結果應使用正確的 HTTP 狀態碼,這樣呼叫者才可以了解 API 實際運行狀況,這邊整理常見的狀態碼,若要了解完整狀態碼說明可參考 wiki-List of HTTP status codes

    • 2xx 成功運行
      • 200-OK 成功回傳結果
      • 201-Created 資源新增成功
      • 202-Accepted 請求接受,但結果還在處理
      • 204-No Content 沒有回應任何內容
    • 3xx 重新導向
      • 301-Moved Permanently 重新導向URI
      • 304-Not Modified 請求資源並未修改
    • 4xx 用戶端錯誤
      • 400-Bad Request 錯誤請求
      • 401-Unauthorized 使用者尚未通過身份驗證
      • 403-Forbidden 用戶端被禁止使用此請求
      • 404-Not Found 請求資源不存在
      • 405-Method Not Allowed 不支援請求的 Http method
      • 414-Url Too Long URI太長
    • 5xx 伺服器錯誤
      • 500-Internal Server Error 內部伺服器錯誤

    這邊也推薦大家可以參考 HTTP DECISION DIAGRAM 來了解每個 Http 狀態運行的活動圖,下圖僅擷取 Request 時的活動圖給予大家進行參考,如果有興趣可以前往觀看完整版。
    https://ithelp.ithome.com.tw/upload/images/20200927/2012117998LYJt5x5y.png

而我們在 Controlelr 中加入的 @RestController 其實是 @Controller + @ResponseBody 組成,@Controller 是將標注(Annotation)的類別注入到 Spring IOC 容器,會讓該類別在運行中會被實例化(Instance),表示該類別具有 Controller 功用,而 @ResponseBody 會將我們函數所回傳的結果轉換為 JSON 格式傳送給 client 端。

這篇文章希望大家能夠先將API概念與RESTful設計概念了解清楚,明日將會介紹前面實作的專案加入 RESTful API 設計風格後的成果

Reference


上一篇
[Day 17] 遠征 Kotlin × 使用 Spring Data JPA 操作資料庫 (2)
下一篇
[Day 19] 遠征 Kotlin × Spring Boot 使用 RESTful API (2)
系列文
30天從零撰寫 Kotlin 語言並應用於 Spring Boot 開發30
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言