ASP.NET Core 5.0 : RESTful API

Published in

Program

9 min readJun 12, 2021

ASP.NET Core 5.0 撰寫RESTful API的新增、查詢、修改、刪除功能，以及參數來源與StatusCodes設定Http Status Code。
最後，在.NET Core使用IHttpClientFactory發出 HTTP Request，呼叫API。

RESTful API

RESTful API 是一種Web API的設計規範。
使用一個URL，並將要執行的動作藏在HTTP 的 method 裡。
以HTTP的請求方法（request methods）來區分要呼叫的是API的哪一種動作(新增、查詢、修改、刪除)。

HTTP的method有以下幾種:

POST／PUT：新增
GET：讀取
PUT：修改（修改整份文件）
PATCH／PUT：修改（修改其中幾個欄位）
DELETE：刪除

以新增訂單來說，RESTful API在不同動作的URL如下:

瀏覽全部訂單 [GET] https://www.xxx.com/order

瀏覽一筆訂單 [GET] https://www.xxx.com/order/訂單編號

新增一筆訂單 [POST]/[PUT] https://www.xxx.com/訂單編號

修改一筆訂單 [PATCH]/[PUT] https://www.xxx.com/order/訂單編號

刪除一筆訂單 [DELETE] https://www.xxx.com/order/訂單編號

RESTful API的好處是，URL看起來乾淨整齊、路徑一致。

若是一般API，則可能瀏覽全部訂單為https://www.xxx.com/order/getall、新增訂單為https://www.xxx.com/order/createorder...等。而且如果每個人的命名習慣不同，那URL的風格可能就會差異更大了。

建立.NET Core Web API專案

建立專案，選擇ASP.NET Core Web API(Framework選擇.NET 5.0)

專案建立完成後，可以看到已經建立了一個WeatherForecastController。

直接F5執行，會看到swagger的頁面。
若是想預設指定頁面，可以在Properties/launchSettings.json的profiles調整launchUrl。

建立API Controller。
Controller右鍵→加入→新增項目。

選擇執行讀取/寫入動作的API控制器。

建立出了有CRUD功能的API Controller。
第11行的[Route("api/[controller]")]設定了API的路徑，也可以依照需求自行調整。

執行後輸入網址 https://localhost:port/api/order，可以看到回傳的字串。
這邊是走Get()的方法，因為URL未包含參數。

輸入網址 https://localhost:port/api/order/1，可以看到回傳的字串。
這邊是走Get(int id)的方法，因為URL包含參數"1"。

參數來源

設定繫結的參數來源，讓API接口知道該從哪裡去取得參數。

若要設定參數來源為何，則可在參數前加上來源屬性，如
public void Get([FromeQuery] string value)。
即可指定參數是由URL中的查詢字串參數而來。

ASP.NET Core 有[FromHeader]、[FromForm]、[FromRoute]、[FromeQuery]、[FromBody]、[FromServices] 等選擇

出處:https://docs.microsoft.com/zh-tw/aspnet/core/web-api/?view=aspnetcore-5.0

Http Status Code

HTTP狀態碼用以表示網頁伺服器回應狀態的3位數字代碼。

當API要回覆Http狀態時，可使用StatusCodes來設定。

HTTP Status Code大致可分為:

1XX HTTP請求已被接收，處理中。
2XX 成功回應。
3XX 重新導向。
4XX 用戶端錯誤，HTTP請求有語法錯誤。
5XX 伺服器錯誤，伺服器處理HTTP請求出錯。

微軟Http Status Code 列舉

[HttpGet] 查詢功能

HttpGet為讀取的method，可以用來撈取(Get)資料。
這邊使用Database-First的方式做資料存取(可參考這裡)。

1.注入DB連線

在OrderController中注入DB連線。

2.設定回傳物件

ActionResult<List<OrderList>> 回傳OrderList物件。

3.設定參數來源

新增一個Class，命名為OrderListParameter，用來傳遞參數

設定參數來源 [FromBody] OrderListParameter parameter。

4.加入查詢條件與StatusCode

最後，加入查詢條件與StatusCode顯示狀態碼與回傳資料。

完整程式碼:

Postman輸入URL與Body參數，即可看到回傳資料。

[HttpPost] 新增功能

HttpPost為新增的method，可以用來新增資料。
這邊使用Database-First的方式做資料存取(可參考這裡)。

程式碼:

Postman輸入URL與Body參數，即可新增，並回傳資料。

[HttpPut] 修改功能

HttpPut為修改的method，可以用來更新資料。
這邊使用Database-First的方式做資料存取(可參考這裡)。

程式碼:

Postman輸入URL與Body參數，即可更新，並回傳資料。

[HttpDelete] 刪除功能

HttpDelete為刪除的method，可以用來刪除資料。
這邊使用Database-First的方式做資料存取(可參考這裡)。

程式碼:

Postman輸入URL與單號參數，即可刪除。

ASP.NET Core 呼叫API

IHttpClientFactory 可以註冊及用來在應用程式中設定和建立 HttpClient 執行個體。
這邊以ASP.NET Core MVC專案呼叫API，並顯示在View頁面。

在Startup.cs中的ConfigureServices方法中加入程式碼services.AddHttpClient();，註冊HttpClientm。

2.在HomeController.cs上方加入下方程式碼，
相依性注入IHttpClientFactory。

3.HomeController新增OrderList()方法。

4. 在OrderList()中傳送 HTTP requests(請求)和接收 HTTP responses(回應)。

設定URL參數
建立API參數
建立HttpRequestMessage，設定HTTP的method、URL與Content
使用IHttpClientFactory建立HttpClient
送出Request，並接收HttpResponseMessage
取得HTTP Content，並轉為物件回傳View()

5.建立OrderList的View。

6._Layout.cshtml中加入OrderList的連結。

7.執行畫面

點選上方OrderList進入頁面。

顯示API回傳的資料。

ASP.NET Core 5.0 : RESTful API

Written by Select *