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格式