【Asp.Net Core - WebAPI】路由設計 & API命名

前言

API的名稱即為資源(Resource)的名稱和所在位置,也稱為URI端點(endpoint) or 路由(routing)。
良好的命名有助於開發和維護😊

命名原則

簡短便於輸入的 URI：

去除無意義且重覆的單詞。
例如 domain/api/v1/employees
使用者能讀懂的 URI：

使用有意義的英文單字,而不使用縮寫。
小寫英文字母的 URI：

一律使用小寫英文字母,更不可大小寫字母混用。
修改方便的 URI：

例如 domain/v1/employees/1, 即可看出該員工 ID 為 1, 而且只要修改 ID 就能獲取其他員工的資源。
不暴露 Server 架構的 URI：

例如 domain/v1/employees.php, 就知道應該是用 PHP 程式語言編寫的,這讓黑客更容易針對漏洞發起惡意攻擊。
規則統一的 URI：

例如使用 :
英文字母複數 domain/v1/employees 來取得所有員工資源組
英文字母單數 domain/v1/employee/1 用來取得一位員工的資源
類似這種不統一的 URI 容易造成 Client 的使用混亂。
使用英文單字名詞的複數。
不使用空格及需要編碼的字元。
使用連接符 - 連結多個英文單字：

但應避免多個英文單字連結,而是使用路徑 / 劃分的方式。
URI 應加入 API 的版本號：如 domain/v1/employees。

路由設計 (asp .net core)

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // 1. 將路由新增至Middleware管線
    app.UseRouting();

    // 2. 加入端點以執行路由,它會執行服務端點的請求委派
    app.UseEndpoints(endpoints =>
    {
        // 加入服務端點
        endpoints.MapControllers();
    });
}

路由名稱的保留字(不能使用❗)
- action
- area
- controller
- handler
- page
屬性路由組成
[Route(“api/v{version:apiVersion}/[controller]/[action]/{id:int}”)]
- 路由前綴 - api/v{version:apiVersion}
- 前綴參數 - {version:apiVersion}
- 路由條件約束 - {id:int}
  - 可以使用Regex規則,但有可能會影響處理效能

心得

好的路由設計,不僅對開發和維護有利之外,對使用者體驗和SEO都很有幫助喔💪

Clark Lin Blog

【Asp.Net Core - WebAPI】路由設計 & API命名

前言

命名原則

路由設計 (asp .net core)

心得

References