ASP.NET Core 2 学习笔记（十二）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
    对同资源可以用链结表达的方式，向下延伸查询或修改。

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

©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 216,258评论 6赞 498
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 92,335评论 3赞 392
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 162,225评论 0赞 353
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 58,126评论 1赞 292
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 67,140评论 6赞 388
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 51,098评论 1赞 295
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 40,018评论 3赞 417
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 38,857评论 0赞 273
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 45,298评论 1赞 310
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 37,518评论 2赞 332
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 39,678评论 1赞 348
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 35,400评论 5赞 343
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 40,993评论 3赞 325
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 31,638评论 0赞 22
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 32,801评论 1赞 268
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 47,661评论 2赞 368
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 44,558评论 2赞 352

推荐阅读更多精彩内容