【服務計算】REST API學習與設計——模仿GithubAPI設計博客網站API

什麼是REST？

REST：全稱Representational State Transferer，是Roy Fielding博士在他的博士論文中提出來的一種軟件架構風格。注意它是一種風格，而不是某個標準或者某個框架。但是根據這中定義的風格編寫Web程序，就會得到一個比較優質的系統。
好，回到REST的理解上，將其名字翻譯過來是“表示層狀態轉移”，很難理解。不妨試着在這個短語前加上一個名詞，Resources，資源表示層狀態轉移，這樣理解起來就要方便得多了。
資源表示層狀態轉移，首先對象是對資源，也就是網絡上傳輸的數據包括各種格式的。那麼表示，就是URL的表示方法，用url來表示一個資源。那麼狀態轉移呢？對應的就是HTTP中的請求：GET、POST、PUT等，通過這些請求實現資源狀態的改變，這就是REST乾的事情。
用知乎上一個高贊回答（@Ivony）概括一下，就是“URL定位資源，用HTTP描述操作”。

瞭解Web API

參考資料：廖雪峯老師的網站
當我們訪問某個URL的時候，往往得到的是一個完整的html頁面，包括了數據以及其渲染的模式，這樣呈現出來的信息可就複雜得多了，包括圖片、表格等形式的信息。可是如果返回的信息是JSON格式？或者直接是二進制字符？這樣機器就能夠直接解析，那麼這就是一個API。
可以看出API將數據或者說資源以URL的形式存到一個地方，進程或者機器通過一些方法取讀取、修改這些數據，從而達到提供服務的目的。
看到這裏，是不是發現跟上面的REST有點像呀？對了這就是爲什麼兩者一拍即合，REST這種風格立刻就流行起來了。
API就是將Web的功能封裝成一個個url的形式，通過API對數據進行操作，分離了前後端代碼。

學習Github-API

參考資料：GithubAPI
可以看到開頭就說明了這個使用了v3的REST API請求，建議通過Accept header來明確請求的版本。
通過查閱資料我們可以發現，有的REST API設計的時候建議在url中加上相應的版本好，這樣的話確實能夠十分明確告訴使用者使用的是什麼版本，而且有着這個信息就可以不需要向後兼容，而且開放API對於多用戶來講十分難以管理版本問題，加上版本好就能很好的把問題交給用戶自己處理。但是這樣也造成一個混亂，多了許多版本的時候需要遷移代碼，版本本來和資源本身沒有關係，URL是表示資源的（前面提到），加入版本號就使得URL的意思更加複雜。相反加在Header中使得url表示更簡潔一點。不同的使用方式，導致不同的設計模式的選擇。
這次就模仿Github使用默認版本號的方式來設計。
Github所有API訪問通過HTTPS來進行，所有數據通過JSON方式進行傳輸。可以包含空白字段，使用null來表示，不會將其省略，保證信息完整。
訪問api.github.com得到以下信息：

可以看到通過訪問不同的url可以獲取不同的資源數據。
首先需要了解以下HTTP的各個操作：

GET
GET 從所給URL中獲取資源以及資源的表示方式。

POST
POST 在所給的 URI 處創建的新資源。

PUT
PUT 在所給的 URI 中創建或替換資源。

PATCH
PATCH 對 URI 中資源執行部分更新。

DELETE
DELETE 刪除位於指定 URI 處的資源。

設計博客網站API

以https://api.blog.com爲例：

獲取用戶信息

GET /users/:username

Response:
{
  "login": "octocat",
  "user_id": 1,
  "url": "https://api.blog.com/users/octocat",
  "html_url": "https://blog.com/octocat",
  "followers_url": "https://api.blog.com/users/octocat/followers",
  "following_url": "https://api.blog.com/users/octocat/following{/other_user}",
 
  "articles_url": "https://api.github.com/users/octocat/articles",
  
  "type": "User",
  "site_admin": false,
  "name": "octocat",
  "company": "",
  "location": "",
  "email": "[email protected]",
  "hireable": false,
  "followers": 20,
  "following": 0,
  "created_at": "2008-01-14T04:33:35Z",
  "updated_at": "2008-01-14T04:33:35Z"
}

獲得某用戶所有文章總覽

GET /users/:userame/articles

Response:
{
	"count": 10,
	{
		"articleID": 1,
		"category": "learning",
		"category_id": "{id}",
		"title": "articleTitle",
		"article_url": "https://blog.com/:username/:article"
		"readings": 10,
		"word_count": 1024,
		"content": "contents...."
		"comment":[
			{
				"id": 1,
				"user": "username",
				"content": "xxx",
			},
			{
				...
			}
		],
		"created_at": "2008-01-14T04:33:35Z",
	    "updated_at": "2008-01-14T04:33:35Z",
	},
    {
     	"articleID"= 2,
     	....
    },
	...
}	 

訪問用戶的某一個指定的文章

GET /users/:username/articles/{article_id}

Response：
{
	"articleID": 1,
	"category": "learning",
	"category_id": "{id}",
	"title": "articleTitle",
	"article_url": "https://blog.com/:username/:article"
	"readings": 10,
	"word_count": 1024,
	"content": "contents...."
	"comment":[
		{
			"id": 1,
			"user": "username",
			"content": "xxx",
		},
		{
			...
		}
	],
	"created_at": "2008-01-14T04:33:35Z",
    "updated_at": "2008-01-14T04:33:35Z",
}

查看某用戶關注信息

GET /users/:username/followers

Response：
{
	"user_id": 5,
	"url": "https://api.blog.com/users/:username",
	"html_url": "https://blog.com/:username",
	"created_at": "2008-01-14T04:33:35Z",
    "updated_at": "2008-01-14T04:33:35Z",
}

獲取用戶下的分類專欄文章

GET /users/:username/category

Response:
{
	"category": "learning",
	"category_id": "{id}",
	"count": 11,
	"articles": [
		{
			"articleID": 1,
			"category": "learning",
			"category_id": "{id}",
			"title": "articleTitle",
			"article_url": "https://blog.com/:username/:article"
			"readings": 10,
			"word_count": 1024,
			"content": "contents...."
			"comment":[
				{
					"id": 1,
					"user": "username",
					"content": "xxx",
				},
				{
					...
				},
			],
		}
	]
}

發佈文章

POST /user/:username/article

獲得Response包括自動生成文章ID，文章標題、分類等信息。

發佈評論

POST /user/:username/articles/:ariticle_id/comment

以當前登錄用戶作爲發起者，對某個文章發起評論。

修改文章

PUT /user/:username/article/:article_id

刪除文章

DELETE /user/:username/article/:article_id

錯誤處理

HTTP錯誤狀態碼非常多，常用的就是以下幾個

API 正常工作 (200, 201)
客戶端錯誤 (400, 401, 403, 404)
服務端錯誤 (500, 503)

404 Not Found

404 Not Found
請求失敗，請求所希望得到的資源未被在服務器上發現。通常在找不到資源時返回這個狀態碼。比如一些不存在的url，或者沒有權限知道的，如私人權限的博客、未通過審覈還沒有成功發佈的博客信息等。

400 Bad Request

由於包含語法錯誤，當前請求無法被服務器理解。通常在url後面會帶有一些過濾信息（這裏沒有設計到），比如跳到某個小標題、指定分類條件之類的。又或者是用到POST、PUT等請求時，需要請求帶有一定格式和必填字段，但是由於這些參數錯誤或者格式不全，就會導致請求不能被服務成功解析，返回400錯誤。

401 Unauthorized

當前請求需要用戶驗證。
通常在沒有登錄的狀態下訪問一些受保護的 API 時會用到這個狀態碼。