今天我們回到 API 設計的部分，來聊聊 Restful 成熟度模型以及 level 3 的 HATEOAS 是如何運作的~

What is RESTful 成熟度

Richardson Maturity Model是由 Martin Fowler 提出的，用來衡量一隻API 的 RESTfulness 程度。這個模型將 REST API 的成熟度分為四個不同的級別，從 Level 0 到 Level 3，每個級別表示該 API 更接近 REST。

• level 1
  • 其實就是把不同的資源映射到不同的路徑，讓每個資源有獨立的 URL，使用起來更清楚，但這時候還沒有用 method 來代表背後的操作，而是會使用 update_order、delete_order 等方式來命名 API
• level 2
  • 這裡指的就是大家比較熟悉的 Method，來代表 API 背後的意義，如 GET、POST、PUT、PATCH 和DELETE。
• level 3
  • 通常 1 和 2 都是大家比較熟悉的了，而 Level 3 的 HATEOAS（Hypermedia As The Engine Of Application State），目的是讓客戶端透過回傳的資源去知道還有哪些其他相關的資源跟如何去操作，而無需事先知道 API 的具體結構或流程。

在 HATEOAS 的設計中，當客戶端向 server 發送請求後，server 的回應不僅會包含請求的資源，還會包含和資源相關的操作連結（hypermedia links），這些連結會描述了接下來可以執行的操作。
e.g. :
-在獲取某客戶端資料後，API 回應中可能會附帶一個連結，告訴使用者如何更新或刪除該用戶。

HATEOAS 的設計除了使 API 減少了客戶端對 API 文件的依賴，也同時提高了系統的可擴展性和靈活性。

HATEOAS 的優點

• 降低耦合：
  • 客戶端和伺服器之間的依賴性減少，伺服器可以隨時更新操作流程，客戶端只需依賴伺服器回傳的 link 和 使用方式即可。
• 可擴展性：
  • API 的使用者不需要知道 API 所有可能的操作，因為伺服器會在每個回應中提供下一步可以執行的操作。
    HATEOAS 的簡單範例
    假設你透過 API 查詢一筆訂單：

{
  "id": 001,
  "name": "TV",
  "links": [
    { "rel": "self", "href": "/orders/001" },
    { "rel": "update", "href": "/orders/001/update" },
    { "rel": "delete", "href": "/orders/001/delete" }
  ]
}

在這個回應中，除了該筆訂單外，你還能看到一些相關操作的連結（如更新或刪除這個訂單的資源）。

最後，我們簡單用 FASTAPI 來實作一個 HATEOAS 吧!

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List

import uvicorn

app = FastAPI()


class User(BaseModel):
    id: int
    name: str
    links: List[dict]


@app.get("/orders/{order_id}", response_model=User)
async def get_order(order_id: int):
    user_data = {
        "id": order_id,
        "name": "Yusinz",
        "links": [
            {"rel": "self", "href": f"/orders/{order_id}"},
            {"rel": "update", "href": f"/orders/{order_id}/update"},
            {"rel": "delete", "href": f"/orders/{order_id}/delete"}
        ]
    }
    return user_data


if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8000)

完成後就可以 call API 看到它的呈現方式囉!

Reference:

• https://www.martinfowler.com/articles/richardsonMaturityModel.html?ref=philsturgeon.com