Restful Web APIs简介

Restful Web APIs: 
概念： 

• 资源：我们所说的URL是一些事物的URL, 比如一个产品，用户或主页。这些通过URL命名的事物叫资源。 
• 资源的表述：web浏览器为一个资源发送http请求后，服务器会发送一个文档作为响应（通常是一个HTML文档，但有时候是二进制图片或其它东西）。无论服务器发送了什么文档，我们都将这个文档称为资源的表述。 
• 可寻址性： 每个资源应该有一个属于自己的URL。 
• 短会话： HTTP会话只维持在一次请求过程中，客户端发送请求，服务器进行响应。 
• 应用状态： REST里，我们将所停留在哪个特定的页面，称为应用状态。 
• 资源状态： 服务器中存储着各种资源，这些资源的状态就叫做资源状态。GET方法不会改变资源状态。 
• 幂等性（idempotence）： Delete一个资源后，这个资源就消失了，当再次发送delete请求时，可能会收到响应404，但是资源状态和第一次delete 
• 资源后的一致。 

HTTP GET方法： 意思是告诉服务器"把这个资源的表述提供给我" 
HTTP response分为3部分： 

1. 状态码； 
2. 消息体； 
3. 响应报头。重要的报头是Context-Type,它向客户端说明了如何去理解实体消息体，我们将其值称为实体消息体的媒体类型。常见类型有text/html(针对HTML),以及图片类型image/jpeg。application/json: 将约束建立在普通文本之上；application/vnd.collection+json:将约束建立在JSON之上，遵守Collection + Json的约束，是一种描述http资源的列表，例如：

        {

     "collection": {

"href": "http://www.youtypeitwepostit.com/api/"

     }

         }      

 

curl命令：
curl -H "Context-Type:application/vnd.collection+json" -d "{"template":{"data":[{"prompt":"Text of message","name":"text","value":"squid"}]}}" 


HTTP Method: 

• GET:  请求一个资源的表述，是一个安全的HTTP method。 
• DELETE: 删除一个资源，是一个不安全的HTTP method. 
• POST: 1> POST-to-append 向某个资源发送一条POST请求用以在该资源的下一集中创建新的资源。当客户端发送一个POST-to-append请求时，会在实体消息体中添加希望创建的资源的表述信息并发送给服务器，响应201（created：创建成功）或202（Accept：打算创建但还未创建）；POST方法既不安全也不幂等，例如如发送同样的POST请求，则会创建5个内容相同的资源。 
• PUT: 1> 修改一个资源。修改成功后的响应：200（OK）或204（No Content）状态码。 2> 如果客户端知道新资源的URL的话，PUT方法同样可以用来新建一个资源。 PUT请求也是幂等性的，既发送10次同样的PUT请求，和发送一次是一样的（就算是用来新建资源，也是幂等的，和POST请求不同的是，就算多次发送PUT请求，也只会创建一个资源）。 
• PATCH: PATCH方法允许客户端可以只修改资源状态中很小的一部分，和将完整的表述信息通过PUT请求发送出去不同，你可以建立一个特别的"diff"表述，并将它作为PATCH请求的负载数据发送个服务器。 响应：如果服务器想要向客户端发送数据（比如已经更新资源的表述），那么200是最好的选择；若服务器仅仅想要表述执行已经成功，那么204（No Content）就已经足够。PATCH方法既不保证安全，也不幂等。 
• LINK和UNLIKE: 用于管理资源间的超媒体链接。幂等，但不安全。 
• HEAD: 轻量级版本的GET方法，服务器会像处理GET一样处理HEAD方法，但不需要发送实体消息体，只需发送HTTP状态码和报头。 用此方法替代GET不会节约时间（服务器还是需要生成所有的HTTP报头），但可以节约带宽的使用。 
• OPTIONS: 请求的返回包含一个Allow报头，这个报头展示了这个资源所支持的所有method。（该方法无法理解PATCH,LINK和UNLINK方法）。

设计良好的API会为GET请求发送超媒体文档作为响应，并用这个文档来宣传一个资源的功能。这些文档中的链接和表单阐明了客户端下一步所能发起的HTTP请求。而设计低劣的API，使用人类可读的文档来说明客户端能发起哪种HTTP请求。 

HTML文档的协议语义只支持GET和POST方法。 

REST系统：服务器、客户端、缓存、代理、缓存代理等。 


常见的HTML控件允许服务器可以向客户端描述如下4中类型的HTML请求：

1. <a>标签描述一个针对特定URL的GET请求，该请求只会在用户触发控件时产生； 
2. <img>标签描述了一个针对特定URL的GET请求，它将会在后台自动发起； 
3. 拥有method="POST"属性的<form>标签描述了一个针对特定URL的POST请求，该请求将会拥有一个由客户端构造的实体消息体。该请求只会在用户触发控件时产生。 
4. 拥有method="GET"属性的<form>标签描述了一个针对由客户端构造的自定义URL的GET请求。该请求只会在用户触发控件时产生。 

HTML表单 VS URI模板: 
HTML超媒体控件无法告诉浏览器如何创建一个像http://www.youtypeitwepostit.com/search/rest这样的URL。但另一种超媒体技术-URI模板可以做到。 
URI模板： http://www.youtypeitwepostit.com/search/{search} 
http://www.youtypeitwepostit.com/message/?query={query} 
HTML表单： 
<form method="GET" action="http://www.youtypeitwepostit.com/message/"> 
<input type="text" id="query" name="query" /> 
<input type="submit" name="Search"> 
</form> 


URIs, URLs, and URNs: 
首先，URI，是uniform resource identifier，统一资源标识符，用来唯一的标识一个资源。而URL是uniform resource locator，统一资源定位器，它是一种具体的URI， 
即URL可以用来标识一个资源，而且还指明了如何locate这个资源。而URN，uniform resource name，统一资源命名，是通过名字来标识资源，比如mailto:[e-mail]。 
也就是说，URI是以一种抽象的，高层次概念定义统一资源标识，而URL和URN则是具体的资源标识的方式。URL和URN都是一种URI。 


HTTP请求：方法、目标URL、HTTP报头和实体消息体