服務計算——設計博客網站API

REST API規範

REST API簡介

REST（Representational State Transfer），意爲表現層狀態轉移。是一種軟件架構模式，用來描述創建HTTP API的標準方法。其目標是“使延遲和網絡交互最小化，同時使組件實現的獨立性和擴展性最大化”。
API（Application Programming Interface）應用程序接口，用來描述一個類庫的特徵，以及如何去使用它。

基於HTTP構建的設計原則

一般來說，HTTP又如下幾種請求方法：

• GET方法用來獲取資源
• PUT方法可用來新增/更新Store類型的資源
• PUT方法可用來更新一個資源
• POST方法可用來創建一個資源
• POST方法可用來觸發執行一個Controller類型資源
• DELETE方法用於刪除資源

Github API內容

在瀏覽器中輸入https://api.github.com/users/用戶名 可以查看github用戶的個人信息
如以下是查看我的github個人信息時獲得的內容：

{
  "login": "akanine",
  "id": 39228116,
  "node_id": "MDQ6VXNlcjM5MjI4MTE2",
  "avatar_url": "https://avatars2.githubusercontent.com/u/39228116?v=4",
  "gravatar_id": "",
  "url": "https://api.github.com/users/akanine",
  "html_url": "https://github.com/akanine",
  "followers_url": "https://api.github.com/users/akanine/followers",
  "following_url": "https://api.github.com/users/akanine/following{/other_user}",
  "gists_url": "https://api.github.com/users/akanine/gists{/gist_id}",
  "starred_url": "https://api.github.com/users/akanine/starred{/owner}{/repo}",
  "subscriptions_url": "https://api.github.com/users/akanine/subscriptions",
  "organizations_url": "https://api.github.com/users/akanine/orgs",
  "repos_url": "https://api.github.com/users/akanine/repos",
  "events_url": "https://api.github.com/users/akanine/events{/privacy}",
  "received_events_url": "https://api.github.com/users/akanine/received_events",
  "type": "User",
  "site_admin": false,
  "name": null,
  "company": null,
  "blog": "",
  "location": null,
  "email": null,
  "hireable": null,
  "bio": null,
  "public_repos": 13,
  "public_gists": 0,
  "followers": 1,
  "following": 0,
  "created_at": "2018-05-13T00:47:20Z",
  "updated_at": "2019-10-27T10:12:25Z"
}

訪問https://api.github.com/users/用戶名/repos
會得到github用戶倉庫的有關信息：

[
  {
    "id": 217836185,
    "node_id": "MDEwOlJlcG9zaXRvcnkyMTc4MzYxODU=",
    "name": "Automatic-Patrol",
    "full_name": "akanine/Automatic-Patrol",
    "private": false,
    "owner": {
      "login": "akanine",
      "id": 39228116,
      "node_id": "MDQ6VXNlcjM5MjI4MTE2",
      "avatar_url": "https://avatars2.githubusercontent.com/u/39228116?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/akanine",
      "html_url": "https://github.com/akanine",
      "followers_url": "https://api.github.com/users/akanine/followers",
      "following_url": "https://api.github.com/users/akanine/following{/other_user}",
      "gists_url": "https://api.github.com/users/akanine/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/akanine/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/akanine/subscriptions",
      "organizations_url": "https://api.github.com/users/akanine/orgs",
      "repos_url": "https://api.github.com/users/akanine/repos",
      "events_url": "https://api.github.com/users/akanine/events{/privacy}",
      "received_events_url": "https://api.github.com/users/akanine/received_events",
      "type": "User",
      "site_admin": false
    },
    ...

在HTTP API中，JSON因爲它的可讀性、緊湊性以及多種語言支持的優點，成爲最常用的返回格式。
更多的HTTP API設計原則，可以參考文檔

博客網站的API設計

訪問請求

https://api.blog.com

當前版本

可以通過Accept明確請求的API版本，否則可以讓所有請求指向某一確定的版本

Accept: application/vnd.blog.v3+json

獲取概要

curl -i https://api.blog.com/users/用戶名

可以獲得如下信息：

HTTP/1.1 200 OK
Date: Thu, 21 Nov 2019 08:52:15 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1250
Server: nginx
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1574329935
Cache-Control: public, max-age=60, s-maxage=60
Vary: Accept
ETag: "6e5028d4531c997648167ef83559e801"
Last-Modified: Sun, 27 Oct 2019 10:12:25 GMT
...

基本方法

GET

獲取用戶信息：

GET /user/:用戶名

獲取當前用戶的所有blog屬性:

GET /user/用戶名/articles

獲取用戶的單個博客屬性：

GET /user/用戶名/article/博客名

例如：

curl -u -i https://api.blog.com/articles/akanine/blog1/issures?state=closed&sort=clicks"

state表示訪問文章的權限，sort表示文章的排列順序是以點擊量（clicks）進行排列的

POST

用POST請求新建一篇blog：

POST /user/用戶名/博客名

例：

curl -u -i -d '{"title":"...", "content":"...", "public":true, "tag":"...", "description":""}'

PUT

更新一篇blog，使用PUT請求：

PUT /user/用戶名/articles/博客名

例：

curl -u -i https://api.blog.com/articles/akanine/blog1/update -d {"id":"1", "content":"...", "title":"..."}

id表示要修改文章的id

DELETE

刪除一篇博客，使用DELETE請求：

DELETE /user/用戶名/articles/博客名

例：

curl -i -u https://api.blog.com/akanine/delete/article&id = 1

登陸認證

• 基本認證

curl -u "userID" https://api.blog.com

• 登陸失敗
  若輸入未經認證的用戶id或密碼，則會返回錯誤信息401 Unauthorized

curl -i https://api.blog.com -u foo:ba
HTTP/1.1 401 Unauthorized
{
  "message": "Bad credentials",
}

錯誤信息

• 400 Bad Requests: 發送的請求有誤，如語法錯誤、數據格式有誤、缺少必要字段等等

HTTP/1.1 400 Bad Request
Content-Length: 35
{"message":"Problems parsing JSON"}

HTTP/1.1 400 Bad Request
Content-Length: 40
{"message":"Body should be a JSON object"}

• 403 Forbidden 接收到請求，但客戶端權限不足
• 422 Unprocessable Entity 發送無效字段

	HTTP/1.1 422 Unprocessable Entity
	Content-Length: 149
	
	{
	  "message": "Validation Failed",
	  "errors": [
	    {
	      "resource": "Issue",
	      "field": "title",
	      "code": "missing_field"
	    }
	  ]
	}

參考資料：
跟着Github學習Restful HTTP API