服务计算：模仿 Github，设计一个博客网站的 API
总览
-
- 1. 博客网站应该具有的基本能力
- 2. RESTful风格
- 3. 基本规则
- 4. 设计博客网站的REST API
-
- 4.1 查看当前版本
- 4.2 用户登录
- 4.3 查看用户信息
- 4.4 修改用户信息
- 4.5 查看文章
- 4.6 发布文章
- 4.7 删除文章
- 4.8 查看文章评论
- 4.9 发布文章评论
1. 博客网站应该具有的基本能力
- 个人介绍 对于个人博客来说，它首先要支持展示博主的个人介绍。这个个人介绍里面可能包括了昵称、联系方式、相关经历等基本内容，能够让读者能够对这个博客的主人有一个基本的认识。
- 文章的撰写与展示 对一个博客来说，最重要的就是它的内容，也就是里面的文章。一个好用的博客平台应该具备易于让博主撰写文章的能力，让够让博主毫无负担地撰写、编辑自己的文章。此外，还必须能够有层次，条理的展示文章的信息，比如展示标题、节选、封面，创建 /修改时间，评论点赞数等等。
- 归档能力 一篇文章的撰写时间、内容标签 /分类等都是不同的，如何按照不同的要求对这些文章进行归档整理，也是考验博客平台的能力之一。而当文章数量较多的时候，添加一个搜索的功能也能大大方便读者对某博主博客的浏览。
- 博主与读者互动的能力 仅仅只有博主一个人自嗨可能难以激发写作的动力，如果博客能够提供博主与读者互动的能力，将能有效激励博主持续创作，更能提升文章的传播度——点赞和评论功能则是互动能力中最重要的功能之一。
2. RESTful风格
- RESTFUL是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式定义或JSON格式定义。RESTFUL适用于移动互联网厂商作为业务使能接口的场景，实现第三方OTT调用移动网络资源的功能，动作类型为新增、变更、删除所调用资源。
- 特点：
a. 每一个URI代表1种资源；
b. 客户端使用GET、POST、PUT、DELETE4个表示操作方式的动词对服务端资源进行操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源；
c. 通过操作资源的表现形式来操作资源；
d. 资源的表现形式是XML或者HTML；
e. 客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都必须包含理解请求所必需的信息。
3. 基本规则
1）通信协议：API与用户的通信协议，总是使用HTTPs协议。
2）数据格式：统一采用JSON。
3）URI格式统一：同一作者发布另一篇博文，则仅仅改变URI后面的部分，URI的前面部分不应改变。
4）状态码：统一根据HTTP协议：
- 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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
4. 设计博客网站的REST API
4.1 查看当前版本
默认情况下，所有https://api.weblog.com接收当前版本（V1）的REST API的请求。
Accept:application/vnd.weblog.v1+json
注：所有的时间戳都以ISO 8601格式返回：
YYYY-MM-DDTHH:MM:SSZ
4.2 用户登录
curl -u username -p password https://weblog.com/v1
登录成功：返回状态码为：2xx
登录失败：返回状态码为：4xx
注：以下API均在登录的情况下使用。
4.3 查看用户信息
GET /username
curl -u https://weblog.com/v1/huangshim23
响应：
{
Status：200 OK
----------------
"username":huangshim23.
"age":20,
"gender": man,
"fans":null,
"coin":0,
"interestring field":Computing Service,3D,
"created_at":2017-10-01T14:20:35+08:00
}
4.4 修改用户信息
PUT /user
data //修改用户的参数
{
"age": 21,
...
}
curl -u -d {
"age": 21, ...} https://weblog.com/v1/huangshim23
响应：
{
Status：200 OK
----------------
"username":huangshim23.
"age":21,
"gender": man,
"fans":null,
"coin":0,
"interestring field":Computing Service,3D,
"created_at":2017-10-01T14:20:35+08:00
}
4.5 查看文章
1）查看用户发表的所有文章
GET /username/articles
curl -a https://weblog.com/v1/huangshim23/articles
响应：
{
"username":"huangshim23"
"total_num":20,
"articles":[
{
"title":"title1",
"id": 1,
"href":"https://weblog.com/v1/huangshim23/articles/1",
"action":"GET",
"status":"original"
"created_time": "2010-11-11T17:31:50Z",
"updated_time": "2014-11-11T17:58:47Z",
"words": 3000,
"visits": 1000
},
{
"title":"title2",
"id": 1,
"href":"https://weblog.com/v1/huangshim23/articles/2",
"action":"GET",
"status":"reproduced"
"created_time": "2016-11-21T17:31:50Z",
"updated_time": "2018-08-11T17:58:47Z",
"words": 5000,
"visits": 10
},
...
]
}
2）查看特定的文章
GET /username/articles/{
id}
GET /username/articles/{
title}
curl -u https://weblog.com/v1/huangshim23/articles/1
curl -u https://weblog.com/v1/huangshim23/articles/hello-world
响应：
{
"username": huangshim23,
"title":"hello-world",
"id": 1,
"href":"https://weblog.com/v1/huangshim23/articles/1",
"action":"GET",
"status":"original"
"created_time": "2016-11-21T17:31:50Z",
"updated_time": "2018-08-11T17:58:47Z",
"words": 3000,
"visits": 1000
}
4.6 发布文章
POST /user/articles
data //发布文章的数据参数
{
"title":
"content":
"description":
"visibility":
"status":
}
curl -u -p -d '{"title":"xxx","content":"xxx","description":"xxxx","visibility":true, "status": "orginal"}' https://weblog.com/v1/huangshim23/articles
响应：
Status：200 OK
--------------------------
"isPublished":true ,
"article":{
"id": 3,
"title": "articleTitle",
"owner": {
"name": "haungshim23",
"id": 123,
"url": "https://weblog.com/v1/huangshim23",
"type": "User"
},
"article_url": "https://weblog.com/v1/huangshim23/articles/3",
"private": false,
"description": "...",
"reading number": 1,
"created_at": "2016-11-11T17:31:50Z",
"updated_at": "2016-11-11T17:31:50Z",
"words": 1502,
"language": "Chinese",
"content":"article contents...."
}
}
4.7 删除文章
DELETE /user/articles/id
curl -d -i https://weblog.com/v1/huangshim23/articles/1
响应：
Status：200 OK
--------------------------
{
"successed": "true",
"article_id": "1",
"created_at":"2019-09-01T11:30:50Z",
"deleted_at": "2019-11-20T10:30:50Z"
}
4.8 查看文章评论
GET /user/articles/id/comments
curl -u https://weblog.com/v1/huangshim23/articles/1/comments
响应：
{
Status：200 OK
--------------------------
"comments":[
{
"userName":"user1",
"comment": "...",
"comment_time":"2019-11-11T10:30:50Z",
"stars": 100
},
{
"userName":"user2",
"comment": "...",
"comment_time":"2019-11-21T12:30:20Z",
"stars": 1
},
...
]
}
4.9 发布文章评论
POST /user/articles/id/comments
curl -c '评论内容' https://weblog.com/v1/huangshim23/articles/1/comments
响应：
{
"comment_status": "succeeded",
"comment": "评论内容",
"userName": "huangshim23",
"comment_time": "2019-11-21T12:30:20Z"
}