初识 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。

问题1：什么是RestFul风格的接口？

(1).调用者不再根据方法名称区分请求方法，而是通过请求方式进行区分,将所有的操作都抽象成对资源的增删改查。

即：新增用Post请求，查询用get请求，修改用put请求，删除用delete请求。

(2).请求的路径中将不在出现方法名称

(3).用Http的返回状态码表示服务器端的处理结果，eg：找不到用404、没有权限返回201，不在需要自己约定状态码。

(4).有利于系统优化，浏览器可以自动缓存Get请求。

问题2：RestFul风格的弊端

理论性太强，很容易把初学者搞晕，比如 如何通过状态码区分是"账号错误"还是"密码错误"？ 比如"登录"属于什么操作？再比如 一个控制器里有两个方法 GetM1() 和 GetM2(), 两个方法中都没有参数值，这种情况如何通过请求方式来区分呢？再比如 下面的GetStudets(string str) 和 GetTeachers(string str) 方法，参数名都是str，所以无法区分(可以把其中一个参数名改为str2，就不冲突了，或者通过别的路由规则声明一下，或者给标注个非Get请求的标记，比如[HttpPost]总之很麻烦)

　　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");