ASP.NET Core 2 学习笔记（十二）REST-Like API

Restful几乎已算是API设计的标准，通过HTTP Method区分新增(Create)、查询(Read)、修改(Update)和删除(Delete)，简称CRUD四种数据存取方式，简约又直接的风格，让人用的爱不释手。

本篇将介绍如何通过 Core实践REST-Like API。

为什么是REST-Like 而不是 REST?

本文API设计未符合HATEOAS(Hypermedia As The Engine Of Application State)原则，所以不得称为RESTful API。

RESTful API 有四个重要的原则要遵守：

Level 0

使用HTTP做为资料传输的媒介。Level 1

不要提供一个包山包海的API，而是要区分资源，每个资源都该有对应的API。Level 2

透过HTTP Method区分新增(Create)、查询(Read)、修改(Update)跟删除(Delete)。Level 3

对同资源可以用链结表达的方式，向下延伸查询或修改。

参考：HATEOAS

HTTP Method

REST-Like API 对数据的操作行为，通过HTTP Method 分为以下四种方式：

新增(Create)

用HTTPPOST通过Body传递JSON或XML格式的数据给Server。例如：

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

查询(Read)

用HTTPGET通过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)

修改数据如同查询跟新增的组合，用HTTPPUT通过URL带路由参数，找到要修改的目标；再通过Body传递JSON或XML格式的数据给Server。例如：

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

删除(Delete)

删除数据同查询，用HTTPDELETE通过URL带路由参数，找到要删除的目标。例如：

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

HTTP Method Attribute

Core 2 学习笔记（六）MVC有提到，过去 MVC把MVC及Web API的套件分开，但在 Core中MVC及Web API用的套件是相同的。所以只要装Microsoft.AspNetCore.Mvc套件就可以用Web API了。路由方式也跟 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){// ...}}

目前 Core 还没有像 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

过去 Web API 2预设是Pascal Case；而 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

若想保持跟 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名称是延续，虽然名称叫Default，但在 Core它不是Default。CamelCasePropertyNamesContractResolver才是 Core的DefaultContractResolver。

访问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 Core

Attribute Routing in Core

Richardson Maturity Model

HATEOAS

老司机发车啦：/SnailDev/Core2Learning