Service-computing-hw10：模仿Github API编写设计一个博客网站的部分REST API

一些基本规则

PART1 协议

API与用户的通信协议，总是使用HTTPs协议。

PART2 域名

https://api.example.com

PART3 版本

https://api.example.com/v1/

PART4 路径

https://api.example.com/v1/users

PART5 HTTP动词

• GET（SELECT）：从服务器取出资源（一项或多项）。
• POST（CREATE）：在服务器新建一个资源。
• PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
• PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
• DELETE（DELETE）：从服务器删除资源。

GET /users：列出所有用户列表

PART6 过滤信息

• ?limit=10：指定返回记录的数量
• ?offset=10：指定返回记录的开始位置。
• ?page=2&per_page=100：指定第几页，以及每页的记录数。
• ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
• ?animal_type_id=1：指定筛选条件

PART7 状态码

• 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
• 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
• 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
• 204 NO CONTENT - [DELETE]：用户删除数据成功。
• 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
• 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
• 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
• 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
• 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
• 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
• 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
• 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

PART8 数据格式

统一采用json

API列表

登录账号

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

查看发表的所有文章

GET /:username/articles

curl -i -u https://api.example.com/v1/wangjh/articles

Status：200 OK
--------------------------
{
  "total_count": 40,
  "items": [
    {
      "articleID": 1,
      "title": "articleTitle",
      "owner": {
        "name": "ownerName",
        "id": 123,
        "url": "owner blog url",
        "type": "User"
      },
      "article_url": "article url"
      "private": false,
      "description": "...",
      "reading number": 10,
      "created_at": "2010-11-11T17:31:50Z",
      "updated_at": "2018-11-11T17:58:47Z",
      "words": 1502,
      "language": "Chinese",
      "content":"article contents...."
    },
    ...
  ]
}

取得特定的文章

GET /:username/articles/{id}
GET /:username/articles/{title}

curl -u -i https://api.example.com/v1/wangjh/articles/1
curl -u -i https://api.example.com/v1/wangjh/articles/hello-world

搜素文章

POST /:username/articles/?{id}{name}{data}
curl -u -i https://api.example.com/v1/wangjh/articles?id=1&title=xxx&data=xxx
// 至少有一个搜索选项

id	string	文章id
title	string	文章标题
data	string	文章发表日期

查看文章评论

GET /:username/articles/:id/comments

curl -i https://api.example.com/v1/wangjh/articles/1/comments

{
    "id": 1,
    "author": "wangjh",
    "url": "xxx",
    items:[{
	    "contents":"xxx",
	    "user": {
	      "id": 2,
	      "name":"liyuanfang"
	      "url": "xxx",
	      "type": "User",
	      "site_admin": false
	    },
	    ....
    ]
    "created_at": "2111-11-11T02:13:12Z",
    "updated_at": "2111-11-11T11:11:11Z"
  }

创建评论

POST /:user/:id/comment
data //评论参数
{
	"content":"xxx"
}

curl -u -i https://api.example.com/v1/wangjh/articles/1/comments -d {"content":"xxx"}
  {
    "id": 122,
    "author": "wangjh",
    "url": "xxx",
	"contents":"xxx",
	"user":{
		"name": "userName",
        "id": 3,
        "url": "user blog url",
        "type": "User"
	}
    "created_at": "2111-11-11T11:11:11Z"
  }

发布文章

POST /:user/articles

data //发布文章的数据参数
{
	"content":"",
	"title":"",
	"private": true/false,
	"description":""
}
curl -u -i -d '{"title":"xxx","content":"xxx","private":false,"description":"xxx"}' https://api.example.com/v1/wangjh/articles

Status：200 OK
--------------------------
	"isPublished":true ,
	"article":{
      "articleID": 2,
      "title": "articleTitle",
      "owner": {
        "name": "ownerName",
        "id": 123,
        "url": "owner blog url",
        "type": "User"
      },
      "article_url": "article url"
      "private": false,
      "description": "...",
      "reading number": 1,
      "created_at": "2010-11-11T17:31:50Z",
      "updated_at": "2018-11-11T17:58:47Z",
      "words": 1502,
      "language": "Chinese",
      "content":"article contents...."
    }
}

删除文章

DELETE /:user/articles/{id}

修改文章

PUT /:user/articles/{id}

data //修改文章的参数
{
    "content":"",
	"title":"",
}
    
curl -u -i -d {"title":"","content":"xxx"} https://api.example.com/v1/wangjh/articles/1/

查看关注者

GET /:username/followers

查看被关注者

GET /:username/followering