RESTFul&HTTP GET简介

RestApi：https://www.cnblogs.com/springyangwc/archive/2012/01/18/2325784.html

RESTFul API设计指南：http://www.ruanyifeng.com/blog/2014/05/restful_api.html这篇是阮一峰老师写的

RESTFul

　　由Roy Fielding提出的，RESTFul是一种架构风格，这种风格基于一套预定义的规则，这些规则描述了网络资源是如何定义和寻址的。

　　1、资源：万物看成资源

　　2、统一接口：CRUD，跟Http Method对应。Create---Post、Read----Get、Update---Put/Patch、Delete----Delete。

　　3、URI：统一资源定位符，资源对应的唯一地址

　　4、无状态：基于HTTP协议的，前后是不关联的。（登录系统---查询工资---计算税收，这 是有状态的）。无状态的意思就是，直接一个地址，就能拿到工资，就能得到税收。

RESTFul的6个约束，每一个约束对API都有正面或负面的影响

　　REST所关注的性能，可扩展、间接性、互操作性、通讯可见性、组件便携性和可靠性都包含在这6个约束里。

　　1、客户端-服务端约束：客户端和服务端是分离的，它们可以独自的进化

　　2、无状态：客户端和服务端的通讯必须是无状态的，状态应该包含在请求里的，也就是说请求里要包含服务端需要的所有的信息，以便服务端可以理解请求并可以创造上下文

　　3、分层系统：就像其他的软件架构一样REST也需要分层结构的，但是不允许某层直接访问不相邻的层

　　4、统一接口：这里分为4点，他们是，资源标识符（URI）、资源的操作（也就是方法Method，HTTP动词）、自描述的响应（可以认为是媒体类型Media-Type）、以及状态管理（超媒体作为应用状态的引擎HATEOAS，Hypermedia as the Engine of Application State）

　　5、缓存：缓存约束派生于无状态约束，它要求从服务端返回的响应必须明确表明是可缓存的还是不可缓存的

　　6、按需编码：这允许客户端可以从服务端访问特定的资源而无需知晓如何处理它们，服务端可以扩展或自定义客户端的功能。

REST-Richardson成熟度模型代表API的成熟度，分4级，0最差，3最好。

　　0级，Plain Old XML沼泽：这里HTTP协议只是被用来进行远程交互，协议的其余部分都用错了，都是RPC风格的实现（例如SOAP，尤其是使用WCF的时候）

　　1级，资源：每个资源都映射到一个URI上了，但是HTTP方法并没有正确的使用，结果的复杂度不算太高

　　2级，动词：正确使用了HTTP动词，状态码也正确的使用了，同时也去掉了不必要的变种

　　3级，超媒体：API支持超媒体作为应用状态的引擎HATEOAS，Hypermedia as theEngine of Application State，引入了可发现性

HTTP GET Action

　　API资源命名资源应该是用动词，它是个东西，不是动作

　　资源应该使用名词，例如：

　　　　api/getusers  这个就是不正确的

　　　　GET api/users  就是正确的，或者GET api/users/{userId}

　　其中资源名的单词我喜欢使用复数的形式

　　API资源命名--层次结构：

　　　　例如 api/department/{departmentId}/emoloyess，这几表示了department（部门）和员工（employee）之间是主从关系。而api/department/{departmentId}/emplss/{emploId}，这就表示了该部门下的某个员工。

　　API资源命名--过滤排序

　　　　过滤和排序，不是资源，应该作为参数，例如：

　　　　api/users？orderby=username

　　API资源的ID

　　　　资源的URI应该是永远都一样的，推荐GUID作为ID来使用，自增int类型的ID，在迁移到新数据库时需要特殊设定，保证ID值不会发生变化。

HTTP方法与资源交互

 

 注意：

　　HEAD：和GET差不多，但是它不应该返回响应的body，所以没有响应的payload，它主要是用来获取资源的一些信息，例如查看资源是否可用等

　　OPTIONS：它是用来查询某个资源URI的可交互方式有哪些，换句话时候就是，使用它可用知道某个URI是否可用执行GET或者POST动作，这些动作通常是在响应的Header是里面而不是body里，所以也没有响应的payload。

状态码

　　可以参考：http://tool.oschina.net/commons?type=5

　　状态码会告诉API的消费者，请求是否如逾期的成功，或者失败。如果出现了错误，谁该为这个错误负责。

　　API主要用到了：

　　　　200级别，表示成功

 

　　　　400级别，表示客户端引起的错误

　　　　500级别，表示服务器错误

内容协商：

　　如果资源支持多种展现格式，那么消费者可以选择它想要的格式。在请求的Accept Header指定Media Type ，application/json，application/xml，若未指定，默认返回application/json，请求的media type不可用时，并且消费者不支持默认格式，返回406

APS.NET Core里的内容协商：

　　ASP.NET Core支持输出和输入两种格式化器。

　　　　用于输出的media type放在Accept Header里，表示客户端接受这种格式的输出。

　　　　用于输入的media type放在Content-Type Header里。表示客户端传进AI的数据是这种格式。

　　　　ReturnHttpNotAcceptable设为true，就会返回406.