服务计算——设计博客网站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