Restful API架構(gòu)
RESTful（Representational State Transfer）是目前最流行的一種互聯(lián)網(wǎng)軟件架構(gòu)啄刹。它結(jié)構(gòu)清晰繁成、符合標(biāo)準(zhǔn)忆嗜、易于理解己儒、擴(kuò)展方便，所以正得到越來越多網(wǎng)站的采用捆毫。
但是闪湾，到底什么是RESTful ?
REST這個詞，是Roy Thomas Fielding在他2000年的博士論文中提出的绩卤。Fielding是一個非常重要的人途样，他是HTTP協(xié)議（1.0版和1.1版）的主要設(shè)計(jì)者江醇、Apache服務(wù)器軟件的作者之一、Apache基金會的第一任主席何暇。
目標(biāo)：一個功能強(qiáng)陶夜、性能好、適宜通信的架構(gòu)
My work is motivated by the desire to understand and evaluate the architectural design of network-based application software through principled use of architectural constraints, thereby obtaining the functional, performance, and social properties desired of an architecture.
資源（Resources）
REST的名稱"表現(xiàn)層狀態(tài)轉(zhuǎn)化"中裆站，省略了主語条辟。"表現(xiàn)層"其實(shí)指的是"資源"（Resources）的"表現(xiàn)層"。
所謂"資源"宏胯，就是網(wǎng)絡(luò)上的一個實(shí)體羽嫡，或者說是網(wǎng)絡(luò)上的一個具體信息。它可以是一段文本肩袍、一張圖片杭棵、一首歌曲、一種服務(wù)氛赐，總之就是一個具體的實(shí)在颜屠。你可以用一個URI（統(tǒng)一資源定位符）指向它，每種資源對應(yīng)一個特定的URI鹰祸。
表現(xiàn)層（Representation）
"資源"具體呈現(xiàn)出來的形式
HTTP請求的頭信息中用Accept和Content-Type字段
比如甫窟，文本可以用txt格式表現(xiàn)，也可以用HTML格式蛙婴、XML格式粗井、JSON格式表現(xiàn)，甚至可以采用二進(jìn)制格式街图；圖片可以用JPG格式表現(xiàn)浇衬，也可以用PNG格式表現(xiàn)。
狀態(tài)轉(zhuǎn)化（State Transfer）
上網(wǎng)瀏覽餐济，就代表了客戶端和服務(wù)器的一個互動過程耘擂。在這個過程中，勢必涉及到數(shù)據(jù)和狀態(tài)的變化絮姆。
現(xiàn)今所有網(wǎng)絡(luò)訪問都使用HTTP協(xié)議醉冤，這是個無狀態(tài)的協(xié)議，所有狀態(tài)保存在Server端篙悯，Client如果想要改變其狀態(tài)蚁阳，只能借助表現(xiàn)層。具體來說鸽照，就是HTTP協(xié)議里面螺捐，四個表示操作方式的動詞：GET、POST、PUT定血、DELETE赔癌。它們分別對應(yīng)四種基本操作：GET用來獲取資源，POST用來新建資源（也可以用于更新資源）澜沟，PUT用來更新資源届榄，DELETE用來刪除資源。
總結(jié)
我們總結(jié)一下什么是RESTful架構(gòu)：
【笪埂（1）每一個URI代表一種資源铝条；
（2）客戶端和服務(wù)器之間席噩，傳遞這種資源的某種表現(xiàn)層班缰；
（3）客戶端通過四個HTTP動詞悼枢，對服務(wù)器端資源進(jìn)行操作埠忘，實(shí)現(xiàn)"表現(xiàn)層狀態(tài)轉(zhuǎn)化"。
Restful API 設(shè)計(jì)
- 協(xié)議
- HTTPS + JSON.
- DateTime ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
版本（Version）
版本通常用于API大版本的修改和發(fā)布馒索，同時又要兼容老版本API而使用的一種方法莹妒。
主要的版本方案有：
URLPath版本（openstack）
AcceptHerder版本（github）
QueryParameter版本
Namesspace版本（django支持）路徑（Endpoint）
路徑又稱"終點(diǎn)"（endpoint），在RESTful架構(gòu)中绰上，每個網(wǎng)址代表一種資源（resource）旨怠，所以網(wǎng)址中不能有動詞，只能有名詞蜈块，而且所用的名詞往往與數(shù)據(jù)庫的表名對應(yīng)鉴腻。一般來說，數(shù)據(jù)庫中的表都是同種記錄的"集合"（collection）百揭，所以API中的名詞也應(yīng)該使用復(fù)數(shù)爽哎。分頁（Pagination）
通常使用特定查詢參數(shù)用于分頁，例如：
curl 'https://api.github.com/user/repos?page=2&per_page=100'
在響應(yīng)時器一，通常也會用一個特定的字段說明next last first prev等url
- HTTP動詞
GET（SELECT）：從服務(wù)器取出資源（一項(xiàng)或多項(xiàng)）课锌。
POST（CREATE）：在服務(wù)器新建一個資源。
PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）祈秕。
PATCH（UPDATE）：在服務(wù)器更新資源（客戶端提供改變的屬性）渺贤。
DELETE（DELETE）：從服務(wù)器刪除資源。
HEAD：獲取資源的元數(shù)據(jù)踢步。
OPTIONS：獲取信息癣亚，關(guān)于資源的哪些屬性是客戶端可以改變的丑掺。
- 過濾信息（Filtering）
API應(yīng)該提供參數(shù)获印，過濾返回結(jié)果。
?limit=10：指定返回記錄的數(shù)量
?offset=10：指定返回記錄的開始位置。
?page=2&per_page=100：指定第幾頁兼丰，以及每頁的記錄數(shù)玻孟。
?sortby=name&order=asc：指定返回結(jié)果按照哪個屬性排序，以及排序順序鳍征。
?animal_type_id=1：指定篩選條件
- 狀態(tài)碼（Status Codes）
服務(wù)器向用戶返回的狀態(tài)碼和提示信息黍翎，常見的有以下一些（方括號中是該狀態(tài)碼對應(yīng)的HTTP動詞）。
200 OK - [GET]：服務(wù)器成功返回用戶請求的數(shù)據(jù)艳丛，該操作是冪等的（Idempotent）匣掸。
201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數(shù)據(jù)成功。
202 Accepted - [*]：表示一個請求已經(jīng)進(jìn)入后臺排隊(duì)（異步任務(wù)）
204 NO CONTENT - [DELETE]：用戶刪除數(shù)據(jù)成功氮双。
400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發(fā)出的請求有錯誤碰酝，服務(wù)器沒有進(jìn)行新建或修改數(shù)據(jù)的操作，該操作是冪等的戴差。
401 Unauthorized - [*]：表示用戶沒有權(quán)限（令牌送爸、用戶名、密碼錯誤）暖释。
403 Forbidden - [*] 表示用戶得到授權(quán)（與401錯誤相對）袭厂，但是訪問是被禁止的。
404 NOT FOUND - [*]：用戶發(fā)出的請求針對的是不存在的記錄球匕，服務(wù)器沒有進(jìn)行操作纹磺，該操作是冪等的。
406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式亮曹，但是只有XML格式）爽航。
410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的乾忱。
422 Unprocesable entity - [POST/PUT/PATCH] 當(dāng)創(chuàng)建一個對象時讥珍，發(fā)生一個驗(yàn)證錯誤。
500 INTERNAL SERVER ERROR - [*]：服務(wù)器發(fā)生錯誤窄瘟，用戶將無法判斷發(fā)出的請求是否成功衷佃。
- 錯誤處理（Error handling）
如果狀態(tài)碼是4xx，就應(yīng)該向用戶返回出錯信息蹄葱。一般來說氏义，返回的信息中將error作為鍵名，出錯信息作為鍵值即可图云。
{
error: "Invalid API key"
}
- 返回結(jié)果
GET /collection：返回資源對象的列表（數(shù)組）
GET /collection/resource：返回單個資源對象
POST /collection：返回新生成的資源對象
PUT /collection/resource：返回完整的資源對象
PATCH /collection/resource：返回完整的資源對象
DELETE /collection/resource：返回一個空文檔
- Hypermedia API
RESTful API最好做到Hypermedia惯悠，即返回結(jié)果中提供鏈接，連向其他API方法竣况，使得用戶不查文檔克婶，也知道下一步應(yīng)該做什么。
- 其他
驗(yàn)證方式
請求頻率限制
條件約定：ETag Last-Modified
JSONP
參考：
restful api 架構(gòu)理解： http://www.ruanyifeng.com/blog/2011/09/restful.html
restful api 設(shè)計(jì)指南： http://www.ruanyifeng.com/blog/2014/05/restful_api.html
Github REST API v3：https://developer.github.com/v3
