Ultimate ASP.NET CORE 6.0 Web API --- 读书笔记（20 - 23）

20 Data Shaping

本文内容来自书籍： Marinko Spasojevic - Ultimate ASP.NET Core Web API - From Zero To Six-Figure Backend Developer (2nd edition)
需要本书和源码的小伙伴可以留下邮箱，有空看到会发送的

Data Shaping（不知道应该翻译成什么），它是一个减少从服务器返回给客户端的流量的方法。
它允许 API 的使用者通过查询字符串选择字段来选择(塑造)数据。

比如：
https://localhost:5001/api/companies/companyId/employees?fields=name,age

它可以通过给API消费者一个选择，选择它们需要的数据返回，这样服务器的压力会减小，但是这不是每个API都需要的功能。而且我们需要思考清楚并决定，我们是不是要实现它，因为实现涉及很多关于反射的操作，这会让我们的APP变慢

（没有遇到过这种用法，暂时不做了解）

21 Supporting HATEOAS

HATEOAS：Hypermedia as the Engine of Application State，是REST中的一个重要的约束，如果没有这个，那么RESTAPI不能被称作RESTful，而我们通过实现REST架构的好处也很多都没有了

Hypermedia：超媒体，指的是包含了可以链接到其他资源的内容，也就是资源之间是连通的

REST架构允许我们动态地生成Hypermedia links在我们的响应中，因此让导航更加容易。想象一下，一个网站，里面有一些Hypermedia区帮助你导航到其他的网站中的不同部分，而在REST中，HATEOAS也可以实现相同的功能

21.1.1 Typical Response with HATEOAS Implemented

一旦实现了HATEOAS，那么我们响应就像是图中展示的这样，我们可以知道所有的员工信息，而且对每一个员工可以执行的操作，都列举出来了。这样一个API，是具有自我发现和演进的，也就是如果服务器的API可能被修改了，那么一般情况下，客户端的代码也会需要修改，但是如果具有自我发现，客户端的代码也就不需要修改了

href，代表一个目标URI
rel，代表一个链接的关联类型，或者说描述当前这个上下文和目标资源之间的关系
method，需要的HTTP方法

21.1.3 Pros/Cons of Implementing HATEOAS

实现HATEOAS的好处：

API变得具有自我发现和探索
客户端可以通过链接实现逻辑，它变得更加容易，而且所有发生的变化都会直接地反映在客户端上
服务器驱动应用程序状态和 URL 结构，而不是相反。
链接关系可以用来指向开发人员的文档
通过超链接进行版本控制变得更加容易
减少无效状态事务调用
API 可以在不破坏所有客户端的情况下进化

实现HATEOAS所有的特性并不简单，所有我们需要记住我们API的范围，如果想要实现的话，而且不同场景下的API（大量对外公开的和同一个系统间通信的）是很不一样的

22 Working With OPTIONS And HEAD Requests

OPTIONS: 使用请求某个资源上具有选项或者操作

[HttpOptions]
public IActionResult GetCompaniesOptions()
{
    Response.Headers.Add("Allow", "GET, OPTIONS, POST");
    return Ok();
}

HEAD: 和GET方法一样，但是没有响应体，它是用来确认资源的有效性、访问性和最近修改

[HttpGet]
[HttpHead]
public async Task<IActionResult> GetEmployeesForCompany(Guid companyId, [FromQuery] 
EmployeeParameters employeeParameters)

23 Root Document

Root Document: 是API消费者的起点，或者说，是消费者学习如何使用我们的restAPI

[Route("api")]
[ApiController]
public class RootController : ControllerBase
{
    private readonly LinkGenerator _linkGenerator;
    public RootController(LinkGenerator linkGenerator) => 
        _linkGenerator = linkGenerator;
}

然后是我们的这个控制器，只有一个action，那就GET方法，返回link，包含所有的顶级资源的可用操作

比如company和employee，我们只是返回company，因为employee是隶属company

或者从另外一个角度查看，应该返回什么链接，从我们URI中可以看到

/api是返回的文档和所有顶级链接；

/api/companies是在api下的顶级资源URI，所以应该返回所有/api/{resources}这种格式相关联的action的HTTP方法，然后以此类推，这就像是在一个有向图中，顶点每个出度就是一个链接