ASP NET Core ---REST & HTTP GET

參照 草根專欄- ASP.NET Core + Ng6 實戰：https://v.qq.com/x/page/h0764n405ll.html

一、REST (Representational State Transfer)

由Roy Fielding提出的.
REST 是一種架構的風格, 這種風格基於一套預定義的規則, 這些規則描述了網絡資源是如何定義和尋址的.

1、REST的6個約束

每一個約束對API都有正面或負面的影響

REST所關注的性能, 可擴展性, 簡潔性, 互操作性, 通訊可見性, 組件便攜性和可靠性都包含在這6個約束里.

• 客服端-服務端約束: 客戶端和服務端是分離的, 它們可以獨自的進化.
• 無狀態: 客戶端和服務端的通信必須是無狀態的, 狀態應包含在請求里的. 也就是說請求里要包含服務端需要的所有的信息, 以便服務端可以理解請求並可以創造上下文.
• 分層系統: 就像其它的軟件架構一樣, REST也需要分層結構, 但是不允許某層直接訪問不相鄰的層.
• 統一接口: 這里分為4點, 他們是: 資源標識符(URI), 資源的操作(也就是方法Method, HTTP動詞), 自描述的響應(可以認為是媒體類型Media-Type), 以及狀態管理(超媒體作為應用狀態的引擎 HATEOAS, Hypermedia as the Engine of Application State).
• 緩存: 緩存約束派生於無狀態約束, 它要求從服務端返回的響應必須明確表明是可緩存的還是不可緩存的.
• 按需編碼: 這允許客戶端可以從服務端訪問特定的資源而無須知曉如何處理它們. 服務端可以擴展或自定義客戶端的功能.

2、REST – Richardson成熟度模型

代表API的成熟度, 分4級, 0最差, 3最好.

• 0級, Plain Old XML沼澤: 這里HTTP協議只是被用來進行遠程交互, 協議的其余部分都用錯了, 都是RPC風格的實現(例如SOAP, 尤其是使用WCF的時候).
• 1級, 資源: 每個資源都映射到一個URI上了, 但是HTTP方法並沒有正確的使用, 結果的復雜度不算太高.
• 2級, 動詞: 正確使用了HTTP動詞, 狀態碼也正確的使用了, 同時也去掉了不必要的變種.
• 3級, 超媒體: API支持超媒體作為應用狀態的引擎 HATEOAS, Hypermedia as the Engine of Application State, 引入了可發現性.

 

二、Action

1、API 資源命名

資源應該使用名詞, 它是個東西, 不是動作

資源應該使用名詞, 例:

• api/getusers 就是不正確的.
• GET api/users 就是正確的
• GET api/users/{userId}.

其中資源名的單詞我喜歡使用復數的形式.

2、命名層次結構

• 例如 api/department/{departmentId}/emoloyees, 這就表示了department (部門)和 員工(employee)之前是主從關系.
• 而 api/department/{departmentId}/emoloyees/{employeeId}, 就表示了該部門下的某個員工.

3、命名排序過濾

       過濾和排序, 不是資源, 應作為參數.

• 例如 api/users?orderby=username

4、API資源的ID

       資源的URI應該永遠都是一樣的.

• 推薦GUID應該作為ID來使用.
• 自增int類型的ID, 在遷移到新數據庫時需要特殊設定, 保證ID值不會發生變化.

5、HTTP方法和資源交互

• HEAD: 和GET差不多, 但是它不應該返回響應的body, 所以沒有響應的payload. 它主要使用來獲取資源的一些信息, 例如查看資源是否可用等.
• OPTIONS: 它是用來查詢某個資源URI的可交互方式有哪些, 換句話說就是, 使用它可以知道某個URI是否可以執行GET或者POST動作, 這些結果通常是在響應的Headers里面而不是body里, 所以也沒有響應的payload. 

6、狀態碼

• 200級別, 表示成功.
• 400級別, 表示客戶端引起的錯誤.
• 500級別, 表示服務器錯誤.

     （1）2xx狀態碼：

• 200 - OK
• 201 - Created，表示資源創建成功了
• 204 - No content，成功執行，但是不應該返回任何東西

     （2）4xx狀態碼：

• 400 - Bad request，表示API的消費者發送到服務器的請求是錯誤的
• 401 - Unauthorized，表示沒有權限
• 403 - Forbidden，表示用戶驗證成功，但是該用戶仍然無法訪問該資源
• 404 - Not found，表示請求的資源不存在
• 405 - Method not allowed，這就是當我們嘗試發送請求給某個資源時，使用的HTTP方法卻是不允許的，例如使用POST api/countries, 而該資源只實現了 GET，所以POST不被允許
• 406 - Not acceptable，這里涉及到了media type，例如API消費者請求的是application/xml格式的media type，而API只支持application/json
• 409 - Conflict，表示該請求無法完成，因為請求與當前資源的狀態有沖突，例如你編輯某個資源數據以后，該資源又被其它人更新了，這時你再PUT你的數據就會出現409錯誤；有時也用在嘗試創建資源時該資源已存在的情況。
• 415 - Unsupported media type，這個和406正好返回來，比如說我向服務器提交數據的media type是xml的，而服務器只支持json，那么就會返回415
• 422 - Unprocessable entity，表示請求的格式沒問題，但是語義有錯誤，例如實體驗證錯誤。

      （3）5xx狀態碼：

• 500 - Internal server error，這表示是服務器發生了錯誤

7、HTTP GET

• 單個數據

          找到了: 200
          沒找到: 404

        [HttpGet("{Id}")]
        public async Task<IActionResult> Get(int Id)
        {

            var post = await _postRepository.GetPostId(Id);
            if(post==null)
            {
                return NotFound();
            }
            var postDTO = _mapper.Map<Post, PostDTO>(post);
            return Ok(postDTO);

        }

• 集合數據

           至少有一條數據, 200
           沒有數據, 也是200

        [HttpGet]
        public async Task<IActionResult>  Get()
        {
            var posts = await _postRepository.GetPosts();
            var postDto=_mapper.Map<IEnumerable<Post>,IEnumerable<PostDTO>>(posts);
            return Ok(postDto);
        }

8、內容協商

        如果資源支持多種展現格式，那么消費者可以選擇它想要的格式

• 在請求的Accept Header指定Media Type

          application/json, application/xml

• 若未指定, 返回默認 application/json

          請求的media type不可用時, 並且消費者不支持默認格式, 返回406

 

9、ASP.NET Core 里的內容協商

       ASP.NET Core支持輸出和輸入兩種格式化器.

• 用於輸出的media type放在Accept Header里, 表示客戶端接受這種格式的輸出.
• 用於輸入的media type放Content-Type Header里, 表示客戶端傳進來的數據是這種格式.
• ReturnHttpNotAcceptable設為true, 就會返回406.

            services.AddMvc(option=> {
                option.ReturnHttpNotAcceptable = true;
                option.OutputFormatters.Add(new XmlDataContractSerializerOutputFormatter());
            }); //服務器設置返回xm格式