ASP.NET Core 5 EP 9：什麼是RESTful API？直接寫第一支HTTP GET API吧

ASP.NET Core 5 Web API開發實錄 / 2021-10-29 / Jovepater

什麼是RESTful API

RESTful API全名為Representational State Transfer Application Programming Interface，它不是一種開發規範，而僅是一種風格，藉由HTTP協定的發送要求(Request)與回應(Response)來達成客戶端與伺服器端的溝通，而傳送的內容經常是Json格式，既輕巧又格式化。

維基百科的介紹與說明：連結

HTTP Method

RESTful API完全基於HTTP協定，所以當然支援HTTP的請求方法，包含GET、POST、PUT、DELETE、HEAD、CONNECT、OPTIONS、TRACE與PATCH，不同的方法代表不同的意思與用途，如下表：

只用GET、POST與HEAD

由上述可以發現，HTTP請求方法有九種，分別代表不同的用途與目的，但在此，僅建議使用GET、POST與HEAD，因為，大多數的伺服器都將GET、POST與HEAD等少數方法以外的HTTP方法排除在外，畢竟，這些HTTP方法都是協定規定的，若隨便執行一個DELETE就能刪除檔案或各種資源，那可是非常嚴重的事情。

所以在此建議，撰寫RESTful API時，操作資料與HTTP請求方法如下表：

如何開始撰寫RESTful API

ASP.NET Core Web API專案中放置API程式的地方是Controller目錄，為了方便管理與辨識，在這個Controller目錄裡面的程式檔案都在檔名的字尾加上Controller，例如RecipeController.cs。

第一支GET API

步驟1：在Controller目錄下新增一個RecipeController.cs，內容如下：

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;

namespace CookbookApi.Controllers
{
    // 將API的路徑調整為https://{ip or hostname}:{port}/api/recipe/...
    [Route("api/[controller]")]
    public class RecipeController : Controller
    {
        // 宣告Log介面，導入NLog機制
        private readonly ILogger<RecipeController> _logger;

        public RecipeController(ILogger<RecipeController> logger)
        {
            _logger = logger;
        }
    }
}

步驟2：我們要新增一個GET方法的API，目的是讓客戶端獲得糖醋排骨食譜的訊息，如下：

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;

namespace CookbookApi.Controllers
{
    [Route("api/[controller]")]
    public class RecipeController : Controller
    {
        private readonly ILogger<RecipeController> _logger;

        public RecipeController(ILogger<RecipeController> logger)
        {
            _logger = logger;
        }

        // 設定這個API使用GET方法
        [HttpGet]
        public IActionResult Get()
        {
            // 宣告一個食譜的Ｍodel，並呼叫Libs.Recipe.Get函數取得資料
            Models.Resipe objResipe = Libs.Recipe.Get();
            // 回傳HTTP 200，內容為糖醋排骨的食譜資料
            return Ok(objResipe);
        }
    }
}

步驟3：存擋後，以指令來建制專案，並執行。

$ dotnet build
Microsoft (R) Build Engine for .NET 16.11.0+0538acc04 版
Copyright (C) Microsoft Corporation. 著作權所有，並保留一切權利。

  正在判斷要還原的專案...
  所有專案都在最新狀態，可進行還原。
  CookbookApi -> /Users/xxx/Desktop/CookbookApi/bin/Debug/net5.0/CookbookApi.dll

建置成功。
    0 個警告
    0 個錯誤

經過時間 00:00:02.60
$ dotnet run
正在建置...
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: http://localhost:5000
...
...

步驟4：打開瀏覽器連接到https://localhost:5001/swagger，可以看到Swagger的Web UI，如下圖：

步驟5：點選/api/Recipe旁的”Try it out”，後點選Executer(執行)，可以看到API Server回覆HTTP Code 200，回覆內容為糖醋排骨這道菜的資料，ASP.NET Core很聰明的幫我們自動轉換成Json格式，如下：

1. API方法的URI與名稱
2. 執行API的按鈕
3. API請求的URL
4. API回覆HTTP Code
5. API回覆的HTTP Body
6. API回覆的HTTP Header

我們已經完成一支以GET方法取得字串資料的API了，這也是透過API取得資料最基本也最常用的方式，接下來，再寫一支POST方法的API吧！

~ END ~

ASP.Net Core, HTTP GET, Web API