初识 ASP.NET Web API（01）
目录：
- Web API概念
- Web API默认路由
- 什么是Restful
一.什么是Web API?
- 只操作数据。
- 是一个在.NET框架上构建Web API的框架,可以构建由多种客户端访问的HTTP服务,一种RestFul风格的开发接口的技术，它比WebService更省流量，比WCF更简单。
- SingalR主要负责构建实时服务。
二.WebApi的功能特点
- 支持RestFul风格、方法返回值直接返回对象、独立于IIS部署、方法可以直接声明为async、支持MVC大部分功能。
三.WebApi和MVC的区别
- MVC关心页面和数据，Api只关心数据
- 独立于IIS部署
- 可直接通过请求方式来确认请求哪个接口，MVC需要Action来确定
- 更轻量更适合构建APP的接口服务
四.WebApi的默认路由
routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional }
)；
五.什么是RestFul
- 状态性转移，一组架构约束条件和原则。
- 目前通过HTTP实现
- 通过请求方式进行区分、请求路径不在出现方法名称、有自己的状态码、有利于系统优化，自动缓存Get请求
六.RestFul设计
- 遵循统一接口原则
1、协议
API与用户的通信协议，总是使用HTTPs协议。
2、域名
https://api.example.com
3、版本
https://api.example.com/v1/
4、路径
表示具体网址 https://api.example.com/v1/zoos
5、HTTP动词
Get（获取资源）、Post（提交资源）、Put（更新后）、Patch（更新）、Delete（删除）、HEAD（获取元数据）、Options（获取信息）
6、过滤信息
提供参数，过滤返回结果，存在冗余
7、状态码
200（OK 成功）、201 （Created 新建或修改数据成功）、202（表示一个请求已进入后台排队）、204（删除数据成功）、400（发出的请求错误，没有执行操作，是空的）、401（没权限）
403（得到授权，但禁止访问）、404（针对的不存在的记录，空的）、406（请求的格式不可得）、410（请求的资源永久被删除）、422（创建对象发生验证错误）
500（服务器发生错误，无法判断用户发生的请求是否成功）
8、错误处理
返回的信息中将error作为键名，出错信息作为键值即可。
9、返回结果
不同的操作返回不同的结果
10、Hypermedia API
即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。
{"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}
rel表示这个API与当前网址的关系(collection关系，并给出该collection的网址)，href表示API的路径，title表示API的标题，type表示返回类型。
11、其他
- API的身份认证应该使用OAuth 2.0框架。
- 服务器返回的数据格式，应该尽量使用JSON，避免使用XML。
|
12、生成API帮助文档
- 通过Nuget安装：Microsoft.AspNet.WebApi.HelpPage，选中项目，右键属性，勾上xml文档文件，找到 Areas/HelpPage/App_Start 目录下的HelpPageConfig.cs 文件，Register 方法，添加一行代码
（config.SetDocumentationProvider(new XmlDocumentationProvider(AppDomain.CurrentDomain.BaseDirectory + "bin\\api.xml"));）
- 通过Nuget安装SwaggerUI生成API文档，选中项目，右键属性，勾上xml文档文件，在SwaggerConfig.cs文件中 搜c.IncludeXmlComments(GetXmlCommentsPath());
c.IncludeXmlComments(AppDomain.CurrentDomain.BaseDirectory + "bin\\05-WebApiExtend.xml");
