restful接口

HTTP

http请求组成

http请求由三部分组成，分别是：请求行、消息报头、请求正文

GET / HTTP/1.1 #请求行
Host: www.baidu.com
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:31.0) Gecko/20100101 Firefox/31.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: zh-cn,zh;q=0.8,en-us;q=0.5,en;q=0.3
Accept-Encoding: gzip, deflate
Cookie: BAIDUID=0C92D17D8B11016B6A003A4906F22D1A:FG=1; BD_UPN=133143; BD_HOME=0 #cookie
Connection: keep-alive
Cache-Control: max-age=0

http响应组成

HTTP响应也是由三个部分组成，分别是：状态行、消息报头、响应正文

HTTP/1.1 200 OK #状态行
Date: Wed, 06 Aug 2014 01:15:50 GMT
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Connection: Keep-Alive
Vary: Accept-Encoding
Cache-Control: private
Cxy_all: baidu+d17511e0ab71b0a7bef3c03c854b9a6b
Expires: Wed, 06 Aug 2014 01:15:50 GMT
X-Powered-By: HPHP
Server: BWS/1.1
BDPAGETYPE: 1
BDQID: 0xa7bd03f00008d58f
BDUSERID: 0
Set-Cookie: BDSVRTM=12; path=/
BD_HOME=0; path=/
Content-Encoding: gzip

restful定义

REST(Representational State Transfer表述性状态转移)是一种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。
如果一个架构符合REST原则，就称它为RESTful架构。

REST的概念和准则

1. 网络上的所有事物都被抽象为资源（resource）；
2. 每个资源对应一个唯一的资源标识（resource identifier）；
3. 通过通用的连接器接口（generic connector interface）对资源进行操作；
4. 对资源的各种操作不会改变资源标识；
5. 所有的操作都是无状态的（stateless）。

需要注意的是，REST是设计风格而不是标准。REST通常基于使用HTTP，URI，和XML以及HTML这些现有的广泛流行的协议和标准。

传统模式与REST模式的比较

作用	传统模式	REST模式
列举出所有的用户	GET /users/list	GET /users
列出ID为1的用户信息	GET /users/show/id/1	GET /users/1
插入一个新的用户	POST /users/add	POST /users
更新ID为1的用户信息	POST /users/mdy/id/1	PUT /users/1

接口设计

协议

API与用户的通信协议，总是使用HTTPs协议。
HTTPS和HTTP的区别

• https协议需要到ca申请证书，一般免费证书很少，需要交费。
• http是超文本传输协议，信息是明文传输，https 则是具有安全性的ssl加密传输协议。
• http和https使用的是完全不同的连接方式，用的端口也不一样，前者是80，后者是443。
• http的连接很简单，是无状态的；HTTPS协议是由SSL+HTTP协议构建的可进行加密传输、身份认证的网络协议，比http协议安全。

域名

应该尽量将API部署在专用域名之下。
如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

https://example.org/api/

版本

应该将API的版本号放入URL。

https://api.example.com/?version=1.0

另一种做法是，将版本号放在HTTP头信息中。关于是否将版本信息放入url还是放入请求头有过争论. 学术界说它应该放到header里面去，但是如果放到url里面我们就可以跨版本的访问资源了，而且更加方便和直观

路径

在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。
举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

https://api.example.com/zoos
https://api.example.com/animals
https://api.example.com/employees

HTTP动词

对于资源的具体操作类型，由HTTP动词表示。
常用的HTTP动词有下面五个（括号里是对应的SQL命令）。

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。
HEAD：获取资源的元数据。
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

下面是一些例子。

GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。
下面是一些常见的参数。

?fields=*:返回所有字段
?fields=name|headimgurl:罗列返回字段
?fields=*|_name|age:排除字段
?page=2&size=10：第2页,每页10条记录
?order=name&sort=desc：指定返回结果按照哪个属性排序，以及排序顺序。

状态码

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。。
404 NOT FOUND - []：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
500 INTERNAL SERVER ERROR - []：服务器发生错误，用户将无法判断发出的请求是否成功。

返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范。

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档

鉴权

restful API是无状态的也就是说用户请求的鉴权和cookie以及session无关，每一次请求都应该包含鉴权证明。

通过使用ssl我们可以不用每次都提供用户名和密码：我们可以给用户返回一个随机产生的token。这样可以极大的方便使用浏览器访问API的用户。这种方法适用于用户可以首先通过一次用户名-密码的验证并得到token，并且可以拷贝返回的token到以后的请求中。如果不方便，可以使用OAuth 2来进行token的安全传输。

使用restful接口

<?php
function post($url,$data){
	$ch = curl_init ();
	// print_r($ch);
	curl_setopt ( $ch, CURLOPT_URL, $url );
	curl_setopt ( $ch, CURLOPT_POST, 1 );
	curl_setopt ( $ch, CURLOPT_HEADER, 0 );
	curl_setopt ( $ch, CURLOPT_RETURNTRANSFER, 1 );
	curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);       
	curl_setopt ( $ch, CURLOPT_POSTFIELDS, $data );
	$out = curl_exec ( $ch );
	curl_close ( $ch );
	return $out;
}

function delete($url){
	$ch= curl_init ();
	curl_setopt ( $ch, CURLOPT_URL,$url);
	curl_setopt ( $ch, CURLOPT_FILETIME, true );
	curl_setopt ( $ch, CURLOPT_FRESH_CONNECT, false );
	curl_setopt ( $ch, CURLOPT_HEADER, true );
	curl_setopt ( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt ( $ch, CURLOPT_TIMEOUT, 5184000 );
	curl_setopt ( $ch, CURLOPT_CONNECTTIMEOUT, 120 );
	curl_setopt ( $ch, CURLOPT_NOSIGNAL, true );
	curl_setopt ( $ch, CURLOPT_CUSTOMREQUEST, 'DELETE' );
	$out = curl_exec ( $ch );
	curl_close ( $ch );
	return $out;
}

function put($url,$data){
    //$data为数组
    $ch = curl_init(); //初始化CURL句柄
    curl_setopt($ch, CURLOPT_URL, $url); //设置请求的URL
    curl_setopt($ch, CURLOPT_RETURNTRANSFER,1); //设为TRUE把curl_exec()结果转化为字串，而不是直接输出
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "put"); //设置请求方式
    curl_setopt($ch,CURLOPT_HTTPHEADER,array("X-HTTP-Method-Override: put"));//设置HTTP头信息
    $data=http_build_query($data);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);//设置提交的字符串
    $document = curl_exec($ch);//执行预定义的CURL
    curl_close($ch);
    return $document;
}
?>

调试工具

• HttpRequester
• curl
• firebug

一些restful api示例

• http://open.sinastorage.com/?c=doc&a=api#head_object
• https://developer.github.com/v3/
• https://developers.google.com/gmail/api/v1/reference/users/drafts/create