模仿 Github,设计一个博客网站的 API
尝试建立一个RESTful风格的API,在此之前需要了解什么是REST。REST – REpresentational State Transfer,翻译成中文是“表层状态转移”。简单来说,就是使用URI定位资源,并用统一的接口来操作资源。接下来将以https://blog.com为例,设计一个对用户博客资源的基本操作API。
用户登录
action
在操作用户博客资源之前,需要登录授权。指令如下,使用curl命令在-u参数后输入用户名,执行命令后会要求用户输入密码,若密码正确则登录成功,否则登录失败。
curl -u "user1" https://blog.com
response
登录成功时返回登录信息
{
"message": "Login",
"username": "user1"
}
登录失败时返回错误信息
{
"message": "Bad credentials",
"documentation_url": "https://blog.com"
}
获取博客
action
用户可以通过发送请求来获取博客内容,有以下两种形式
- 请求:GET /username/blogs 获取某个用户的所有博客
- 请求:GET /username/blog 获取某个用户对应id的博客(当前用户下每篇博客都有自己唯一的id)
具体操作如下
获取user1的所有博客
curl -i https://blog.com/user1/blogs
获取user1的博客110
curl -i https://blog.com/user1/blog?id=110
response
返回user1的所有博客信息(此时id为none)
{
“username”: "user1",
"id": none,
"action": GET,
"title": "...",
"content":{
......
}
}
返回user1博客110的信息
{
“username”: "user1",
"id": 110,
"action": "GET",
"title": "...",
"content":{
......
}
}
获取失败时返回错误信息
{
“username”: "user1",
"id": 110,
"action": "GET",
"message": "...",
}
发布博客
action
用户可以通过发送请求来发布自己的新博客,该请求需要登录授权
- 请求:POST /username/publish/blog 发布一篇博客,数据以json格式发送
具体操作如下
user1发布题目为Hello的博客
curl -i https://blog.com/user1/publish/blog -d {"title":"Hello","content":"..."}
response
发布成功,自动为博客创建id并返回博客信息
{
“username”: "user1",
"id": 111,
"action": "PUBLISH",
"title": "Hello",
"content":{
......
}
}
发布失败时返回错误信息
{
“username”: "user1",
"action": "PUBLISH",
"message": "...",
}
更新博客
action
用户可以通过发送请求来更新自己已发布的博客,该请求需要登录授权
- 请求:PUT /username/update/blog 更新对应id的博客,数据以json格式发送
具体操作如下
user1更新博客110
curl -i https://blog.com/user1/update/blog?id=110 -d {"title":"...","content":"..."}
response
更新成功,返回博客信息
{
“username”: "user1",
"id": 110,
"action": "UPDATE",
"title": "...",
"content":{
......
}
}
更新失败时返回错误信息
{
“username”: "user1",
"id": 110,
"action": "UPDATE",
"message": "...",
}
删除博客
action
用户可以通过发送请求来删除自己已发布的博客,该请求需要登录授权
- 请求:DELETE /username/delete/blog 删除对应id的博客
具体操作如下
user1删除博客110
curl -i https://blog.com/user1/delete/blog?id=110
response
删除成功返回操作信息
{
“username”: "user1",
"id": 110,
"action": "DELETE"
}
删除失败时返回错误信息
{
“username”: "user1",
"id": 110,
"action": "DELETE"
"message": "...",
}
获取评论
action
用户可以通过发送请求来获取博客的所有评论
- 请求:GET /username/blog/id/comments 获取对应用户id博客的所有评论
具体操作如下
获取user1博客110的所有评论
curl -i https://blog.com/user1/blog/110/comments
response
返回user1博客110的所有评论信息
{
“username”: "user1",
"id": 110,
"action": "GET COMMENTS",
"content":{
......
}
}
获取失败时返回错误信息
{
“username”: "user1",
"id": 110,
"action": "GET COMMENTS",
"message": "..."
}
发表评论
action
用户可以通过发送请求来对博客发表评论
- 请求:POST /username/publish/blog/id/comment 向对应用户id博客发布一条评论,数据以json格式发送
具体操作如下
对user1博客110发表评论
curl -i https://blog.com/user1/publish/blog/110/comment -d {"content":"..."}
response
发布成功,返回评论信息
{
“username”: "user1",
"id": 110,
"action": "PUBLISH COMMENT",
"content":{
......
}
}
发布失败时返回错误信息
{
“username”: "user1",
"id": 110,
"action": "PUBLISH COMMENT",
"message": "..."
}