作业要求
仿造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"
},
...
]
}