模仿 Github 设计博客网站的 API

一、 作业要求

• 模仿 Github，设计一个博客网站的 API
  
  

二、 REST API 的设计原则

HTTP 协议定义了大量为请求赋于语义的方法。API访问都是通过HTTPS协议进行的，并通过https://api.blog.com进行访问，数据以 JSON 的形式发送和接收

使用 HTTP 设计 RESTful API 时的一些主要原则：

• REST API 围绕资源设计，资源是可由客户端访问的任何类型的对象、数据或服务。
• 每个资源有一个标识符，即，唯一标识该资源的 URI。
• 客户端通过交换资源的表示形式来与服务交互。 许多 Web API 使用 JSON 作为交换格式。
• REST API 使用统一接口，这有助于分离客户端和服务实现。 对于基于 HTTP 构建的 REST API，统一接口包括使用标准 HTTP 谓词对资源执行操作。 最常见的操作是 GET、POST、PUT、PATCH 和 DELETE。
• REST API 使用无状态请求模型。 HTTP 请求应是独立的并可按任意顺序发生，因此保留请求之间的瞬时状态信息并不可行。 信息的唯一存储位置就在资源内，并且每个请求应是原子操作。
• REST API 由表示形式中包含的超媒体链接驱动。

基本操作：

• GET
  GET 检索位于指定 URI 处的资源的表示形式。 响应消息的正文包含所请求资源的详细信息。
  成功的 GET 方法通常返回 HTTP 状态代码 200（正常）。 如果找不到资源，该方法应返回 404（未找到）。

• POST
  POST 在指定的 URI 处创建新资源。服务器为新资源分配 URI，并将该 URI 返回给客户端。 在 REST 模型中，我们经常向集合应用 POST 请求。 新资源将添加到集合中。 还可以使用 POST 请求将待处理数据提交到现有资源，且不创建任何新资源。 请求消息的正文将提供新资源的详细信息。 请注意，POST 还用于触发不实际创建资源的操作。

• PUT
  PUT 在指定的 URI 处创建或替换资源。请求消息的正文指定要创建或更新的资源。客户端指定资源的 URI。请求正文包含资源的完整表示形式。 如果已存在具有此 URI 的资源，则替换该资源。 否则创建新资源（如果服务器支持此操作）。 PUT 请求往往应用到单项资源（例如特定的客户）而不是集合。

• PATCH
  PATCH 对资源执行部分更新。 请求正文包含要应用到资源的一组更改。 客户端指定资源的 URI。这比使用 PUT 更高效，因为客户端只发送更改，而无需发送资源的整个表示形式。

• DELETE
  DELETE 删除位于指定 URI 处的资源。

三、 博客网站 API 设计

• 用户登录博客账号

  用户登录博客账号时需要提供用户名及密码，当用户名与密码匹配时才能够成功登录

  curl -u username:password https://api.example.com

  后面的操作都需要用户登录才能够被允许执行
  当用户登录时的密码或用户名不正确时会获得 404 not Found 的响应
  
  

• 查看用户已发表的博客概览

  GET /username/articles

  应答数据如下，其中包括：博主信息，博主公开文章总数，每篇博文信息概览(文章ID，标题，全文链接，文章类型、发表时间，总字数、访问量等)。

  {
    "username":"user1"
      "total_num":100,
      "articles":[
          {
                "articleID": 17343132,
                "title":"title1",
                "href":"https://api.example.com/xufj/articles/1",
                "private": false,
                "description": "...",
                "created_at": "2018-01-01T00:31:50Z",
                "updated_at": "2019-01-05T17:58:47Z",
                "action":"GET",
                "status":"original"
                "words": 1234,
                "visits": 50
          },
        ...
      ]
  }

• 获得某篇博客的详细内容

  查看（搜索）博客需要提供博主名以及博客ID/博客名，两种查阅博客的方式如下

  GET /username/articles/articleID
  curl -u -i https://api.example.com/xufj/articles/1
  
  GET /username/articles/articleTitle
  curl -u -i https://api.example.com/xufj/articles/test

  应答结果如下

  {
       "articleID": 1,
       "title":"title1",
       "href":"https://api.example.com/xufj/articles/1",
       "private": false,
       "description": "...",
       "created_at": "2018-01-01T00:31:50Z",
       "updated_at": "2019-01-05T17:58:47Z",
       "action":"GET",
       "status":"original"
       "words": 1234,
       "visits": 50，
       "content":"article contents...."
  }

• 获得某篇博客的评论

  查询评论时需要提供博客名或者博客ID

  GET /username/articles/articleID/comments
  curl -u -i https://api.example.com/xufj/articles/1/comments
  
  GET /username/articles/articleTitle/comments
  curl -u -i https://api.example.com/xufj/articles/test/comments

  响应结果如下

  {
      "id": 1,
      "author": "xufj",
      "href": "https://api.example.com/xufj/articles/1",
      items:[{
             "contents":xxx,
             "user": {
                "name":"user2"
                "href": "xxx",
               },
             "created_at": "2018-01-01T00:31:50Z"
           }
             ....
      ]
  }
  

• 发布新博客

  发布博客需要提供新博客的内容及一些相关信息，包括博客名，内容数据，博客类型以及相关描述等

  POST /username/publish/articles
  
  data //文章参数
  {
  	"title":"",
  	"content":"",
  	"private": true/false,
  	"description":""
  }
  
  curl -u -i -d '{"title":"xxx","content":"xxx","private":false,"description":"xxx"}'https://api.example.com/xufj/articles

  发布后的响应结果

  {
   	"articleID": 1,
   	"title":"title1",
   	"href":"https://api.example.com/xufj/articles/1",
   	"private": false,
   	"description": "...",
   	"created_at": "2018-01-01T00:31:50Z",
   	"updated_at": "2018-01-01T00:31:50Z",
   	"action":"POST",
   	"status":"original"
   	"words": 1234,
   	"visits": 0，
   	"content":"article contents...."
  }

• 删除某篇博客

  删除博客需要提供博客ID或者博客名

  DELETE /username/articles/articleID
  curl -u -i https://api.example.com/xufj/articles/1
  
  DELETE /username/articles/articleTitle
  curl -u -i https://api.example.com/xufj/articles/test

  响应结果为博客的删除状态

  {
       "isDeleted":true / false,
       "title":"test",
       "id" : 1
  }
  

• 添加评论

  添加评论需要提供评论的博客信息以及评论内容

  POST /username/articles/articleID/comment
  curl -u -i https://api.example.com/xufj/articles/1
  
  POST /username/articles/articleTitle/comment
  curl -u -i https://api.example.com/xufj/articles/test
  
  data //评论参数
  {
  	"content":"xxx"
  }

  添加评论后响应结果如下

  {
  	"id": 1,
  	"author": "xufj",
  	"href": "https://api.example.com/xufj/articles/1",
  	items:[{
         		"contents":xxx,
         		"user": {
            		"name":"user2"
            		"href": "xxx",
           		},
         		"created_at": "2018-01-01T00:31:50Z"
       		}
  	]	
  }

• 查询用户关注的博主

  GET /username/followers

  {
      "username": "xufj",
      items:[{
         "user": {
            "name":"user2"
            "href": "xxx",
           }
          "start_from": "2018-01-01T00:31:50Z"
         }
         ...
     ]
  }