Rest/Resful簡介

REST是目前最常見的API設計規範

REST 全名為 REpresentationalStateTransfer(表現層狀態移轉)，主要是提供一堆軟體架構設計上的限制

例如：無狀態 (Stateless)、主從式架構 (Client-Server)、一致性的介面 (Uniform Interface) ....等等

一個軟體架構符合REST風格，就可以稱作是RESTful

RESTful API 有以下幾個建議的設計方式

• 回傳格式使用 JSON
• 善用HTTP 動詞(Verbs)
• 善用HTTP 狀態碼(Status Code)
• 盡量使用 SSL 加密連線
• 擁有良好的 APIs 文件
• 限制回傳的欄位 (不要回傳用不到的資料)

常見HTTP 動詞(Verbs)

• GET 讀取資源
• PUT 替換資源
• PATCH 更換資源部分內容
• DELETE 刪除資源
• POST 新增資源

常用HTTP 狀態碼(Status Code)
2XX 成功:
這類型狀態碼，代表請求已成功被伺服器接收、理解、並接受。

• 200 OK
  請求已成功，請求所希望的回應head或資料將隨此回應返回。

3xx 重新導向:
這類狀態碼代表需要客戶端採取進一步的操作才能完成請求。

• 302 Found
  要求客戶端執行臨時重新導向。

4xx 客戶端錯誤:
這類的狀態碼代表了客戶端看起來可能發生了錯誤，妨礙了伺服器的處理。

• 400 Bad Request
  由於明顯的客戶端錯誤，伺服器不能或不會處理該請求。（例如，格式錯誤的請求語法，太大的大小，無效的請求訊息或欺騙性路由請求）
• 401 Unauthorized
  未認證 (簡單一點可以理解成未登入)
• 403 Forbidden
  伺服器已經理解請求，但是拒絕執行它。(簡單一點可理解成已登入，但是存取權限不足)
• 404 Not Found
  請求失敗，找不到資源。
• 405 Method Not Allowed
  請求行中指定的請求方法不能被用於請求相應的資源。(例如，原本需要POST的方法，改用GET呼叫，使用了錯誤的Http Mehod而導致的錯誤)

5xx伺服器錯誤
表示伺服器無法完成明顯有效的請求。

• 500 Internal Server Error
  通用錯誤訊息，伺服器遇到了一個未曾預料的狀況，導致了它無法完成對請求的處理。沒有給出具體錯誤資訊。

更多Status Code

使用dotnet cli搭配EF Core模型來產生API Controllers

在Windows上開發，有著地表最強開發工具Visaul Studio來做為開發的輔助利器，非常容易的就能透過EF Core的Model產生Controller。

在macOS沒有VS可以使用，但又想利用程式自動化產出相對應的內容，這時候就需要使用dotnet aspnet-codegenerator

dotnet aspnet-codegenerator 微軟提供的dotnet cli全域工具，提供生成程式碼的功能，透過cli就能有使用VS快速產生程式碼的體驗

首先先透過 dotnet cli 來安裝 dotnet aspnet-codegenerator

dotnet tool install -g dotnet-aspnet-codegenerator

接著我們首先要準備我們首先要準備好專案以及建立Model，請參照前面的文章建立[Day06]EF Core CodeFirst
建立完畢之後我們需要在專案下安裝Nuget 套件

dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
(需要安裝才能在專案中使用CodeGeneration)
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
(Microsoft.VisualStudio.Web.CodeGeneration.Design 需要搭配此套件才能進行code generation)

安裝完畢之後就可以在專案目錄底下使用dotnet cli 建立我們的controller
dotnet-aspnet-codegenerator controller --controllerName PostController -async -api -actions -m Post -dc BlogContext -outDir Controllers

dotnet aspnet-codegenerator 參數使用參考

產生完的範例：
PostController.cs 中的 PutPost()

[HttpPut("{id}")]
public async Task<IActionResult> PutPost(int id, Post post)
{
    if (id != post.Id)
    {
        return BadRequest();
    }

    _context.Entry(post).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!PostExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

範例可以看到產出來的API的程式碼連各種情境的回應都幫我們做好了

接著透過Postman來測試API是否可以正常運作
（記得將BlogContext 註冊到DI容器中）

可以看到user這欄是null，而user這欄是我們在建立Model的時候，對於關聯表所做的建立，因此其實是不需要用到的欄位，這時候我們可以通過設定，將值為null的欄位忽略掉。
首先到Startup.cs 中的 ConfigureServices()作下列修改

public void ConfigureServices(IServiceCollection services)
{
   services.AddScoped<BlogContext>();
   services.AddControllers()
           .AddJsonOptions(options => 
               {
                   options.JsonSerializerOptions.IgnoreNullValues = true;
               });
}

在AddControllers()後方加入設定，將null的項目都Ignore掉。

就可以看到user因為是null，所以回傳的時候就自動被篩掉了。

Web API 分析器

剛才上面的範例我們也能看到Action中有很多種回應方式，為了讓程式更清晰更好閱讀，
這時候我們就需要用到 Web API 分析器

分析器封裝會通知您下列任何控制器動作：

• 傳回未宣告的狀態碼。
• 傳回未宣告的成功結果。
• 記錄未傳回的狀態碼。
• 包含明確的模型驗證檢查。

備註：Web API 分析器只能在VS 2017+與VS For Mac上才可使用

首先在專案檔(.csproj)中加入

<PropertyGroup>
    <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
</PropertyGroup>

接著我們使用VS for Mac開啟專案，並進到PostController中的PutPost
會看到return的部分底下會有飄底線，接著我們把滑鼠移到return這一行並點選燈泡按鈕

選取Add ProducesResponseType

選取完之後就會看到，Web API分析器幫我們產生的ProducesResponseType

透過分析器產生的ProducesResponseType可以讓我們一眼就清楚看出這個Action會有哪幾種回應，更容易的閱讀我們的程式。

相關參考
dotnet aspnet-codegenerator
使用 Web API 分析器
使用 Web API 慣例