模仿Github API编写设计一个博客网站的部分REST API
总览
- 当前版本
- 架构图
- 摘要表示
- 详细表示
- HTTP动词
- 用户认证
- 基本认证
- 登录限制失败
- 属性操作
- 查看用户信息
- 查看用户所有的博客
- 查看用户在某一分类下的博客
- 查看博客
- 查看博客摘要
- 发布博客
- 修改博客
- 删除博客
- 创建博客评论
- 查看博客评论
- 时区
- 明确提供带有时区信息的ISO 8601时间戳
- 使用用户的最后一个已知时区
- 默认为UTC，没有其他时区信息
- 后续想法
当前版本
默认情况下，所有的https://api.Blog.com接受v1版本的REST API请求。
Accept:application/vnd.Blog.v1+json
架构图
所有的API访问都是通过HTTPS进行的，并且可以通过访问https://api.Blog.com。所有的数据都以JSON的形式发送和接收。`
curl -i https://api.Blog.com/users/octocat/orgs
HTTP/1.1 200 OK
Server: nginx
Date: Fri, 12 Oct 2012 23:33:14 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "a00049ba79152d03380c34652f2cb612"
X-Blog-Media-Type: Blog.v1
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1350085394
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
X-Content-Type-Options: nosniff
包含空白字段，null不能将其省略。
所有的时间戳都以ISO 8601格式返回：
YYYY-MM-DDTHH:MM:SSZ
摘要表示
当您获取博客列表时，响应包括该博客列表的属性子集。
例如：当您想得到博客的列表是，您会得到每个博客列表的总结表示：
GET /user1/blog
详细表示
当您想要获取单个博客时，响应通常包括该博客的所有属性
例如：当您想得到单个博客时，将获得该博客的详细表示：
GET /user1/list1/article1
该文档提供了每种API方法的示例响应。示例响应说明了该方法的所有属性。
HTTP动词
API v1尽可能在每个动作中使用适当的HTTP动词。
| 动词 | 描述 | 返回状态码 |
|---|---|---|
| GET | 用于检索资源 | 200-表示已在响应中发出 404-资源不存在 204-资源有空表示 406-服务端不支持所需表示 503-服务端当前无法处理请求 |
| POST | 创建资源/更新部分资源 | 200-如果现有资源已被更改 201-如果新资源被创建 204-资源有空表示 412- 前置条件失败（如执行条件更新时的冲突）415- 接受到的表示不受支持 |
| PATCH | 部分更新资源 | 400-指代坏请求 409-通用冲突 415- 接受到的表示不受支持 |
| PUT | 创建或替换资源 | 200-如果已存在资源被更改 201-如果新资源被创建 204-资源有空表示 412- 前置条件失败（如执行条件更新时的冲突）415- 接受到的表示不受支持 |
| DELETE | 删除资源 | 200-资源已被删除 303- 其他，如负载均衡 404-资源不存在 503-服务端当前无法处理请求 |
用户认证
可以通过Blog API v1进行身份验证。需要身份验证的请求在某些地方将返回404 Not Found，而不是 403 Forbidden。这是为了防止私有存储库意外泄露给未经授权的用户。
基本认证
curl -u username https://api.Blog.com
在后续弹出的框中输入密码，或者
curl -u username:password https://api.Blog.com
登录限制失败
当使用无效的用户名和密码进行身份验证登录将返回401 Unauthorized:
curl -u errorname:errorpassword https://api/Blog.com
HTTP/1.1 401 Unauthorized
{
"message":"Bad credentials",
"documentation_url":"https://developer.Blog.com/v1"
}
属性操作
查看用户信息
- 该API用来获取用户的所有主要信息
GET /username- 响应：
curl -u kw411718198:123456 https://api/Blog.com/kw411718198
{
Status：200 OK
----------------
"username":kw411718198,
"age":3,
"follower":csdn,
"fans":null,
"coin":0,
"interestring field":AI,Computing Service,
"created_at":2016-01-01T14:20:35+08:00
}
查看用户所有的博客
- 该API用来查看用户的所有博客
GET /username/blog- 响应：
curl -u kw411718198:123456 https://api/Blog.com/kw411718198/blog
{
Status：200 OK
----------------
"total number":15
"list":[
"article1":{
"title":"welcome to csdn!",
"words":255,
"summary":"the article is a example for newcomers.",
"Original"：true,
"created_at": 2016-01-01T14:20:35+08:00,
"modified_at": 2016-01-01T14:20:40+08:00,
"read times":138,
"comments":0
},
"article2":{
....
}
]
}
查看用户在某一分类下的博客
- 该API用来查看用户的博客分类
GET /username/blog/list1- 响应：
curl -u kw411718198:123456 https://api/Blog.com/kw411718198/blog/Computing Service
{
Status：200 OK
----------------
"list name":"Computing Service",
"total number":3,
"list":[
"article1":{
"title":"CLI 命令行实用程序开发实战 - Agenda",
"words":1025,
"summary":"the article is mainly about a programmar development based on CLI.",
"original"：true,
"created_at": 2019-10-24T21:33:05+08:00,
"modified_at": 2019-10-25T21:33:05+08:00,
"read times":52,
"comments":0
},
"article2":{
....
}
]
}
查看博客
- 该API用来查看用户的博客
GET /username/blog/article- 响应：
curl -u kw411718198:123456 https://api/Blog.com/kw411718198/blog/CLI 命令行实用程序开发实战 - Agenda
{
Status：200 OK
----------------
"title":"CLI 命令行实用程序开发实战 - Agenda",
"created_at":2019-10-24T21:33:05+08:00,
"modified_at": 2019-10-25T21:33:05+08:00,
"read times":53,
"listed":"Computing Service",
"original"：true,
"link":https://api/Blog.com/kw411718198/blog/CLI 命令行实用程序开发实战 - Agenda,
"content":"agende项目是一个CLI程序，可以进行用户管理，会议管理等遍历操作。按照本次作业的要求，实现其中的两条指令——register和log in...."
}
查看博客摘要
- 该API用来查看用户编辑的博客摘要
GET /username/blog/article/summary- 响应：
curl -u -d kw411718198:123456 https://api/Blog.com/kw411718198/blog/CLI 命令行实用程序开发实战 - Agenda/summary
{
Status：200 OK
----------------
"title":"CLI 命令行实用程序开发实战 - Agenda",
"created_at":2019-10-24T21:33:05+08:00,
"modified_at": 2019-10-25T21:33:05+08:00,
"read times":53,
"listed":"Computing Service",
"original"：true,
"link":https://api/Blog.com/kw411718198/blog/CLI 命令行实用程序开发实战 - Agenda,
"summary":"agende项目是一个CLI程序，可以进行用户管理，会议管理等遍历操作。按照本次作业的要求，实现其中的两条指令——register和log in。"
}
发布博客
- 该API供用户进行博客发布
POST /username/blog/article- 响应：
curl -u -p kw411718198:123456 {"title":"IT与风险投资","listed":"Computing Service","original":true,"summary":"some thoughts about a book."}https://api/Blog.com/kw411718198/blog
{
Status：200 OK
----------------
"title":"CLI 命令行实用程序开发实战 - Agenda",
"created_at":2019-10-24T21:33:05+08:00,
"modified_at": 2019-10-25T21:33:05+08:00,
"read times":53,
"listed":"Computing Service",
"original"：true,
"link":https://api/Blog.com/kw411718198/blog/CLI 命令行实用程序开发实战 - Agenda,
"summary":"agende项目是一个CLI程序，可以进行用户管理，会议管理等遍历操作。按照本次作业的要求，实现其中的两条指令——register和log in。"
}
修改博客
- 该API供用户进行博客修改
- `PATCH /username/blog/article
- 响应：
curl -u -pt kw411718198:123456 {"content_from":"*****","content_to":"+++++"}https://api/Blog.com/kw411718198/blog/IT与风险投资
{
Status：200 OK
----------------
"title":"IT与风险投资",
"listed":"Computing Service",
"created_at":2019-11-25T21:56:05+08:00,
"modified_at": 2019-10-25T23:33:05+08:00,
"original"：true,
"link":https://api/Blog.com/kw411718198/blog/IT与风险投资,
"content_from":"*****",
"content_to":"+++++"
}
删除博客
- 该API供用户进行博客删除
DELETE /username/blog/article- 响应：
curl -u -d kw411718198:123456 {"title":"IT与风险投资"}https://api/Blog.com/kw411718198/blog/IT与风险投资
{
Status：200 OK
----------------
"title":"IT与风险投资",
"created_at":2019-10-24T21:33:05+08:00,
"deleted_at":2019-10-29T21:33:05+08:00
}
创建博客评论
- 该API供用户进行博客评论的创建
POST /username/blog/article/comments/number- 响应：
curl -u -p sr2630459443:456123 {"comments":"*****"}https://api/Blog.com/kw411718198/blog/IT与风险投资/comments/1
{
Status：201 OK
----------------
"title":"IT与风险投资",
"listed":"Computing Service",
"author":kw411718198,
"commentator":sr2630459443,
"id":1,
"created_at":2019-11-29T21:33:05+08:00,
"comments":"*****"
}
查看博客评论
- 该API供用户查看当前博客的所有评论
GET /username/blog/article/comments- 响应：
curl -u kw411718198:123456 https://api/Blog.com/kw411718198/blog/IT与风险投资/comments
{
Status：200 OK
----------------
"total number":3,
"list":[
"comment1":{
"words":1025,
"id":1,
"commentator":sr2630459443,
"created_at":2019-11-29T21:33:05+08:00,
"praise points":5,
"comments":"*****",
"reply":[
....
]
},
"comment2":{
....
}
]
}
时区
一些创建新博客的请求允许您在指定或生成时间戳时提供时区信息。我们按照优先级顺序应用以下规则，以确定API调用的时区信息。
- 明确提供带有时区信息的ISO 8601时间戳
- 使用用户的最后一个已知时区
- 默认为UTC，没有其他时区信息
明确提供带有时区信息的ISO 8601时间戳
对于允许指定时间戳的API调用，我们使用该确切的时间戳。
这些时间戳看起来像2019-11-22T11:22:06+08:00。
使用用户的最后一个已知时区
如果未明确提供时间戳，并且您对API进行了身份验证的调用，那么我们将使用身份验证用户的最后一个已知时区，当您编辑Blog网站时，最新的时区将会更新。
默认为UTC，没有其他时区信息
如果以上步骤未产生任何信息，我们将UTC用作时区来进行博客更改后的提交时间。
后续想法
在访问的路径结构中，博客主要分布在username/blog目录下，在username的的目录下还将设置例如organization(供用户组成讨论组织)、forum（供用户进行论坛交流）、developer（供用户进行自主的网站开发）等项目。