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