【ASP.Net】如何设计项目中的webapi

平台独立性

任何client都应该可以去访问这些api， 并且不去考虑这些api的内部是如何实现的。所以api需要设计成使用标准的协议， 以及数据交互的机制。

web app提供的service能够具备一定的扩展性

也就是说api的设计人员应该考虑到api可以进行相应的扩展， 这种扩展不应该影响到原来client的继续使用。

Restfull api

api在设计时围绕server提供的资源设计， 并且每个资源要有唯一标识URI用来访问。资源可以是服务， 也可以是数据等。

设计可以支持filter或者数据量限制的api

很多web api在返回结果的时候是一种以collection的形式， 但是并不是server上的资源都要返回， client往往只需要一部分或者分页进行显示， 如果一次性把资源都返回到client， 会占用很多的带宽等资源的浪费。

对于server中比较大的资源文件， 比如图像，大文件， 可以支持分批次的请求这个资源。

比如实现一个head request。 Head request与get request相似， 它在返回的http head里面对这个资源进行描述， body里面是空的。 client根据http request来决定通过get请求获取这个资源的哪部分。
比如下面这个就是一个head request：

HEAD http://adventure-works.com/products/10?fields=productImage HTTP/1.1

然后其返回的结果是：

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: image/jpeg
Content-Length: 4580

Content-Length header 表示资源的总大小,
Accept-Ranges header 表示这个资源支持分段get获取.

client 通过这些信息可以将资源分为数段进行获取， 如下所示:

GET http://adventure-works.com/products/10?fields=productImage HTTP/1.1
Range: bytes=0-2499

Response:

HTTP/1.1 206 Partial Content
Accept-Ranges: bytes
Content-Type: image/jpeg
Content-Length: 2500
Content-Range: bytes 0-2499/4580
[...]

试着将你的web api使用version的方式去控制

实际上这条与2很类似， 是一种很常规的设计api的方式。有的时候当设计出第一版本的web api推出使用后， 会有很多很多逻辑改动， 或者业务需求导致不得不对第一版的api进行大量的改动， 修改resource scheme等。为了保证原有的api能够继续使用， 可以试着对web api进行加version的设计比如：

http://adventure-works.com/v2/customers/3
http://adventure-works.com/customers/3?version=2 （default是1）
///(在header里面加version)
GET http://adventure-works.com/customers/3 HTTP/1.1
Custom-Header: api-version=1 

---

参考链接：
https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-2.1