REST API设计实践-优快云博客

博客网站API的设计

作业要求
REST API
API设计

作业要求

仿造github设计一个博客网站的REST API

REST API

REST是Representational State Transfer，即表现层状态转移的缩写，指的是查看，创建，编辑，删除这几种功能，都能由HTTP中已实现的GET，POST，PUT，DELETE等方法来表示。
API是Application Programming Interface，即是应用程序接口的缩写，用来帮助我们了解我们该如何运用一个库。
其好处包括：

直接通过http协议，不需要额外的协议
面向资源，一目了然，具有自解释性
数据描述简单，一般通过json或者xml做数据通讯

我们假设博客网站的根地址为https://api.kjhmh2blog.com

API设计

用户登录

curl -u username -p password https://api.kjhmh2blog.com

返回的状态码是2xx，表示成功登陆；状态码是4xx，则表明请求异常，常见的错误类型包括：

400 Bad request：指令错误
401 Unauthorized：密码错误
403 Forbidden：访问被禁止
404 Not found：账户不存在

比如，如果返回的是401 Unauthorized：

HTTP/1.1 401 Unauthorized
{
  "message": "Bad credentials",
  "documentation_url": "https://api.kjhmh2blog.com"
}

如果返回的是403 Forbidden：

HTTP/1.1 403 Forbidden
{
  "message": "Maximum number of login attempts exceeded. Please try again later.",
  "documentation_url": "https://api.kjhmh2blog.com"
}

查看某用户发布的所有文章列表

假设用户名为user：

curl -a https://api.kjhmh2blog.com/user/articles

我们返回的json数据格式，可以参考优快云，一篇文章包括了其ID、访问量、获赞、评论等等信息：

{
    "username": "user",
    "numbers": 10,
    "articles": 
    [
	    {
	        "ID": 0,
	        "title": "the title of this article",
	        "description": "the description of this article",
	        "url": "the url of this article",
	        "classification": "3D Game",
	        "owner": "user",
	        "words": 1000,
	        "visits": 100,
	        "thumbs-up": 100,
	        "comments": 10,
	        "private": true,
	        "publishTime": "2019/11/22/09/00/00",
	    },
	    ...
  ]
}

查看某用户的所有粉丝

curl -f https://api.kjhmh2blog.com/user/followers

返回的json数据格式如下，包括粉丝数量以及所有的粉丝用户名：

{
    "user": "user",
    "numbers": 10,
    "followers": 
    [
	    {
	        "user": "user2"
	    },
	    {
	        "user": "user3"
	    },
	    ...
    ]
}

查找某文章

我们可以通过关键词的形式来查找：

curl -s https://api.kjhmh2blog.com/search?keyword='xxx'

也可以通过id的形式来精确查找：

curl -s https://api.kjhmh2blog.com/search?id='12345678'

发布文章

我们定义发布文章的参数表示为：

{
	"title": "the title of the article",
	"private": true,
	"description": "the description of this article"
}

发布某篇文章：

curl -d '{"title":"...","private":true,"description":"..."}' https://api.kjhmh2blog.com/user/published/article

返回的json数据格式，包括了是否发布了某篇文章、以及该文章具体的信息：

{
    "isPublished":true ,
    "article":{
        "ID": 0,
        "title": "the title of this article",
        "description": "the description of this article",
        "url": "the url of this article",
        "classification": "3D Game",
        "owner": "user",
        "words": 2000,
        "visits": 10,
        "thumbs-up": 10,
        "comments": 10,
        "private": true,
        "publishTime": "2019/11/22/10/00/00",
    }
}

删除某篇文章

curl -d https://api.kjhmh2blog.com/user/delete/article?id=1

返回的json数据格式，包括了是否删除了该文章、该文章的id以及删除的时间戳等信息：

{
    "deleted": "true",
    "ID": "1",
    "deleteTime": "2019/11/22/11/00/00"
}

查看某篇文章的评论

curl -i https://api.kjhmh2blog.com/user/articles/1/comments

返回的json数据格式，包括了当前文章的id、作者、url以及所有评论的评论人、内容和时间戳等信息：

{
    "id": 1,
    "author": "user",
    "url": "the url of this article",
    "commments": 
    [
	    {
	        "user": "user2",
	        "contents": "the content of the comment",
	        "createTime": "2019/11/22/12/00/00"
	    },
	    ...
    ]
}

给某篇文章添加评论

curl -c 'comments' https://api.kjhmh2blog.com/user/article/1/comments

返回的json数据格式，包括了用户名、状态、文章的id、评论的内容、评论的创建时间等信息：

{
    "user": "user",
    "status": "success",
    "ID": 1,
    "content": "the content of the comment",
    "createTime": "2019/11/22/13/00/00"
}

给某篇文章点赞

curl -t https://api.kjhmh2blog.com/user/article

返回的json数据格式，包括文章的id、总的点赞数以及有谁给该文章点了赞：

{
    "ID": "1",
    "thumbs-up": 10,
    "from": 
    [
        {
            "user": "user2"
        },
        {
            "user": "user3"
        },
        ...
    ]
}