ASP.NET Core 2 學習筆記（十二）REST-Like API

来源:https://www.cnblogs.com/snaildev/archive/2018/06/06/9143619.html
-Advertisement-
Play Games

Restful幾乎已算是API設計的標準，通過HTTP Method區分新增(Create)、查詢(Read)、修改(Update)和刪除(Delete)，簡稱CRUD四種數據存取方式，簡約又直接的風格，讓人用的愛不釋手。本篇將介紹如何通過ASP.NET Core實踐REST-Like API。 為 ...


Restful幾乎已算是API設計的標準，通過HTTP Method區分新增(Create)、查詢(Read)、修改(Update)和刪除(Delete)，簡稱CRUD四種數據存取方式，簡約又直接的風格，讓人用的愛不釋手。
本篇將介紹如何通過ASP.NET Core實踐REST-Like API。

為什麼是REST-Like 而不是 REST?

本文API設計未符合HATEOAS(Hypermedia As The Engine Of Application State)原則，所以不得稱為RESTful API。

RESTful API 有四個重要的原則要遵守：

  1. Level 0
    使用HTTP做為資料傳輸的媒介。
  2. Level 1
    不要提供一個包山包海的API，而是要區分資源，每個資源都該有對應的API。
  3. Level 2
    透過HTTP Method區分新增(Create)、查詢(Read)、修改(Update)跟刪除(Delete)。
  4. Level 3
    對同資源可以用鏈結表達的方式，向下延伸查詢或修改。
    參考：HATEOAS

HTTP Method

REST-Like API 對數據的操作行為，通過HTTP Method 分為以下四種方式：

  • 新增(Create)
    用HTTP POST通過Body傳遞JSON或XML格式的數據給Server。例如：

POST http://localhost:5000/api/users
{
   "id": 1,
   "name": "SnailDev"
}

  • 查詢(Read)
    用HTTP GET通過URL帶查詢參數。通常查詢單一資源會用路由參數(Routing Parameter)帶上唯一值(Primary Key)；多筆查詢會用複數，而查詢條件用Query String。例如：

# 單筆查詢
GET http://localhost:5000/api/users/1
# 多筆查詢
GET http://localhost:5000/api/users
# 多筆查詢帶條件
GET http://localhost:5000/api/users?q=SnailDev

  • 修改(Update)
    修改數據如同查詢跟新增的組合，用HTTP PUT通過URL帶路由參數，找到要修改的目標；再通過Body傳遞JSON或XML格式的數據給Server。例如：

PUT http://localhost:5000/api/users/1
{
   "name": "SnailDev"
}

  • 刪除(Delete)
    刪除數據同查詢，用HTTP DELETE通過URL帶路由參數，找到要刪除的目標。例如：

DELETE http://localhost:5000/api/users/1

HTTP Method Attribute

ASP.NET Core 2 學習筆記（六）MVC 有提到，過去ASP.NET MVC把MVC及Web API的套件分開，但在ASP.NET Core中MVC及Web API用的套件是相同的。所以只要裝Microsoft.AspNetCore.Mvc套件就可以用Web API了。路由方式也跟ASP.NET Core 2 學習筆記（七）路由 介紹的RouteAttribute差不多，只是改用HTTP Method Attribute。

HTTP Method Attribute 符合RESTful 原則的路由設定方式如下：

[Route("api/[controller]s")]
public class UserController : Controller
{
    [HttpGet]
    public List<UserModel> Get(string q)
    {
        // ...
    }

    [HttpGet("{id}")]
    public UserModel Get(int id)
    {
        // ...
    }

    [HttpPost]
    public int Post([FromBody]UserModel user)
    {
        // ...
    }

    [HttpPut("{id}")]
    public void Put(int id, [FromBody]UserModel user)
    {
        // ...
    }

    [HttpDelete("{id}")]
    public void Delete(int id)
    {
        // ...
    }
}

目前ASP.NET Core 還沒有像ASP.NET MVC 的MapHttpAttributeRoutes 可以綁Http Method 的全局路由，都要在Action 加上HTTP Method Attribute。

SerializerSettings

 用以下代碼，說明SerializerSettings：

public class UserModel
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }    
    public string PhoneNumber { get; set; }
    public string Address { get; set; }
}

// ...

[Route("api/[controller]s")]
public class UserController : Controller
{
  [HttpGet("{id}")]
  public UserModel Get(int id)
  {
      return new UserModel {
          Id = 1,
          Name = "SnailDev"
      };
  }
}

camel Case

過去ASP.NET Web API 2預設是Pascal Case；而ASP.NET Core預設是使用camel Case。
若想要指定用ContractResolver，可以在Startup.cs的ConfigureServices加入MVC服務時，使用AddJsonOptions設定如下：

// ...
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {        
        services.AddMvc()
                .AddJsonOptions(options => 
                {
                    options.SerializerSettings.ContractResolver 
                        = new CamelCasePropertyNamesContractResolver();
                });
        // 同以下寫法：
        // services.AddMvc();
    }
}

訪問http://localhost:5000/api/users/1會返回JSON如下：

{
    "id": 1,
    "name": "SnailDev",
    "email": null,
    "phoneNumber": null,
    "address": null
}

Pascal Case

若想保持跟ASP.NET Web API 2一樣使用Pascal Case，ContractResolver則改用DefaultContractResolver。

// ...
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {        
        services.AddMvc()
                .AddJsonOptions(options => 
                {
                    options.SerializerSettings.ContractResolver 
                        = new DefaultContractResolver();
                });
    }
}

DefaultContractResolver名稱是延續ASP.NET，雖然名稱叫Default，但在ASP.NET Core它不是Default。CamelCasePropertyNamesContractResolver才是ASP.NET Core的Default ContractResolver。

訪問http://localhost:5000/api/users/1會返回JSON如下：

{
    "Id": 1,
    "Name": "SnailDev",
    "Email": null,
    "PhoneNumber": null,
    "Address": null
}

Ignore Null

上述兩個JSON 回傳，都帶有null 的欄位。在序列化的過程，找不到欄位會自動轉成null，傳送的過程忽略掉也沒錯，反而可以節省到一點流量。

// ...
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {        
        services.AddMvc()
                .AddJsonOptions(options => 
                {
                    options.SerializerSettings.NullValueHandling 
                        = Newtonsoft.Json.NullValueHandling.Ignore;
                });
    }
}

訪問http://localhost:5000/api/users/1會返回JSON如下：

{
    "id": 1,
    "name": "SnailDev"
}

示常式序

Startup.cs

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
                .AddJsonOptions(options => {
                    options.SerializerSettings.NullValueHandling
                        = Newtonsoft.Json.NullValueHandling.Ignore;
                });
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseMvc();
    }
}

Models\ResultModel.cs

namespace MyWebsite.Models
{
    public class ResultModel
    {
        public bool IsSuccess { get; set; }
        public string Message { get; set; }
        public object Data { get; set; }
    }
}

用一個ResultModel 來包裝每個API 回傳的內容，不論調用Web API 成功失敗都用此對象包裝，避免直接throw exception 到Client，產生HTTP Status 200 以外的狀態。　

Controllers/UserController.cs

using System.Collections.Generic;
using System.Linq;
using System.Text.RegularExpressions;
using Microsoft.AspNetCore.Mvc;
using MyWebsite.Models;

namespace MyWebsite.Controllers
{
    [Route("api/[controller]s")]
    public class UserController : Controller
    {
        private static List<UserModel> _users = new List<UserModel>();

        [HttpGet]
        public ResultModel Get(string q)
        {
            var result = new ResultModel();
            result.Data = _users.Where(c => string.IsNullOrEmpty(q) 
                                         || Regex.IsMatch(c.Name, q, RegexOptions.IgnoreCase));
            result.IsSuccess = true;
            return result;
        }

        [HttpGet("{id}")]
        public ResultModel Get(int id)
        {
            var result = new ResultModel();
            result.Data = _users.SingleOrDefault(c => c.Id == id);
            result.IsSuccess = true;
            return result;
        }

        [HttpPost]
        public ResultModel Post([FromBody]UserModel user)
        {
            var result = new ResultModel();
            user.Id = _users.Count() == 0 ? 1 : _users.Max(c => c.Id) + 1;
            _users.Add(user);
            result.Data = user.Id;
            result.IsSuccess = true;
            return result;
        }

        [HttpPut("{id}")]
        public ResultModel Put(int id, [FromBody]UserModel user)
        {
            var result = new ResultModel();
            int index;
            if ((index = _users.FindIndex(c => c.Id == id)) != -1)
            {
                _users[index] = user;
                result.IsSuccess = true;
            }
            return result;
        }

        [HttpDelete("{id}")]
        public ResultModel Delete(int id)
        {
            var result = new ResultModel();
            int index;
            if ((index = _users.FindIndex(c => c.Id == id)) != -1)
            {
                _users.RemoveAt(index);
                result.IsSuccess = true;
            }
            return result;
        }
    }
}

執行結果

通過Postman 測試API。

  • 新增(Create)

  • 查詢(Read)

  • 修改(Update)

  • 刪除(Delete)

參考

Routing in ASP.NET Core 
Attribute Routing in ASP.NET Core 
Richardson Maturity Model 
HATEOAS

 

老司機發車啦：https://github.com/SnailDev/SnailDev.NETCore2Learning


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • 在GridControl控制項上綁定圖片的幾種操作方式
    我們知道，基於DevExpress的開發Winform的項目界面的時候，GridControl控制項是經常用來綁定數據的，一般以常規的字元內容為主，有時候也會有圖片的顯示需要，那麼如果顯示圖片，我們應該如何實現呢？本篇隨筆介紹基於原生GridControl控制項的圖片綁定顯示操作和基於我封裝的分頁控制項（... ...
  • 基於Windows 機器學習(Machine Learning)的圖像分類(Image classification)實現
    今天看到一篇文章 Google’s Image Classification Model is now Free to Learn 說是狗狗的機器學習速成課程（Machine Learning Crash Course）現在可以免費學習啦，因為一開始年初的時候是內部使用的，後來開放給大眾了。大家有誰 ...
  • 紙殼CMS 3.0升級.Net Core 2.1性能大提升
    微軟發佈了.Net Core 2.1正式版，紙殼CMS也在第一時間做了升級，並做了一系列的優化和調整，性能大幅提升，並解決了一些歷史遺留問題，添加了一些新功能。 ...
  • 非同步編程基礎
    本質上適合非同步的操作有：HTTP請求，資料庫指令，Web服務調用等。 1、暫停一段時間(以非同步方式)。 以非同步的方式暫停一段時間，這在進行單元測試或者重試延遲時非常有用。 Task類有一個返回Task對象的靜態函數Delay,下麵是其中的一個 一個簡單的指數退避。指數退避是一種重試策略，重試的延遲時 ...
  • SVN 安裝後右鍵出現點擊滑鼠右鍵彈出錯誤提示：CrashHandler initialization error
    SVN 安裝後右鍵出現點擊滑鼠右鍵彈出錯誤提示：CrashHandler initialization error 原因是目標文件夾中缺少SendRpt.exe文件 解決方案：找svn是好的的同事將bin目錄複製替換本地的bin就可以解決 由於沒有找到上傳附件的地方，就沒有上鄙人的bin目錄了，實屬 ...
  • C# Argument 'picture' must be a picture that can be used as an Icon
    Scenario: 創建了一個WinForm的小程式，希望將它顯示在任務欄，所以在工具欄中的“公共控制項”里，拖入NotifyIcon控制項—notifyIcon1，這個是程式運行任務欄右側通知區域圖標顯示控制項，為控制項notifyIcon的屬性Icon添加一個icon圖標，或從代碼中加入。 Issue: ...
  • 使用後臺線程BackgroundWorker處理任務的總結
    在一些耗時的操作過程中，在長時間運行時可能會導致用戶界面 (UI) 處於停止響應狀態，用戶在這操作期間無法進行其他的操作，為了不使UI層處於停止響應狀態，我們傾向推薦用戶使用BackgroundWorker來進行處理，這個後臺的線程處理，可以很好的實現常規操作的同時，還可以及時通知UI，包括當前處理... ...
  • Linq中的Select與Select many
    Select與Select Many 之前在項目中查詢資料庫中的數據，都是通過sql語句來查詢的，但是隨著時代的發展，微軟在.Net Framework 4.5版中推出的一個主要的特性——LINQ。 LINQ是Language Integrate Query的縮寫，意為語言集成查詢。其中有兩種查詢方 ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發（一）：使用.NET MAUI開發第一個安卓APP
    移動開發（一）：使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說，近來想嘗試開發一款安卓APP，考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP，畢竟是使用Visual Studio開發工具，使用起來也比較的順手，結合微軟官方的教程進行了安卓 ...
  • wpf ToggleButton選中效果和一個登錄界面
    前言 QuestPDF 是一個開源 .NET 庫，用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫，它徹底改變了我們生成 PDF 文檔的方 ...
  • 彈幕樹洞項目功能新增篇
    項目地址 項目後端地址： https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址： ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址： http://tree ...
  • 第27篇 sqlserver2022詳細安裝步驟
    話不多說，直接開乾 一.下載 1.官方鏈接下載： https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe，運行開始下載SQL server； 二. ...
  • .NET 開源高性能 MQTT 類庫
    前言 隨著物聯網（IoT）技術的迅猛發展，MQTT（消息隊列遙測傳輸）協議憑藉其輕量級和高效性，已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫，為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog文檔翻譯系列（六） - 可用的接收器、增強器、格式化輸出
    Serilog支持多種接收器用於日誌存儲，增強器用於添加屬性，LogContext管理動態屬性，支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項，適用於不同需求。 ...
  • 警惕 Visual Studio 屬性求值副作用導致邏輯不符合預期
    目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據，爬取信息時需要模擬瀏覽器行為，否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下： 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • [使用目前最新版]HybridCLR6.9.0+YooAsset2.2.4實現純C# Unity熱更新方案 (一)
    1.前言 什麼是熱更新 游戲或者軟體更新時，無需重新下載客戶端進行安裝，而是在應用程式啟動的情況下，在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR，Xlua，ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles，Addressable， ...
  • 在 ASP.NET Core Web API 中使用操作篩選器統一處理通用操作
    本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺，其實像阿裡雲，騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後，它會送 ...
  • 第28篇 如何.net中實現高效可靠數據同步api
    通過以下方式可以高效，並保證數據同步的可靠性 1.API設計 使用RESTful設計，確保API端點明確，並使用適當的HTTP方法（如POST用於創建，PUT用於更新）。 設計清晰的請求和響應模型，以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證，確保接收到的數據符合預期格 ...
所有分類