模仿 Github设计一个博客网站的 API
文章目录
- 预备知识
- 规则
- 用户登录
- 查看用户信息
- 查看某用户所有文章
- 发布文章
- 删除文章
- 查看文章评论
- 发布评论
预备知识
API是Application Programming Interface（应用程序接口）的缩写，它是拿来描述一个类库的特征或是如何去运用它。
HTTP 应答中，需要带一个很重要的字段：status code。它说明了请求的大致情况，是否正常完成、需要进一步处理、出现了什么错误，对于客户端非常重要。状态码都是三位的整数，大概分成了几个区间：
| 状态码 | 含义 |
|---|---|
| 2XX | 请求正常处理并返回 |
| 3XX | 重定向，请求的资源位置发生变化 |
| 4XX | 客户端发送的请求有错误 |
| 5XX | 服务器端错误 |
规则
协议：所有API访问都通过HTTPS
域名：访问 https://api.example.com
数据：所有数据都使用JSON格式发送和接收
URI：同一作者发布另一篇博文，则仅仅改变URI后面的部分，URI的前面部分不应改变。
响应码：2XX表示成功，4XX或5XX表示失败，具体如下：
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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
用户登录
curl -u username -p password https://api.example.com
登录成功：返回状态码为：2xx
登录失败：返回状态码为：4xx
查看用户信息
GET /username
curl -u https://api.example.com/zz
成功
{
Status：200 OK
----------------
"username":zz.
"age":19,
"gender": woman,
"fans":133453,
"coin":0,
"created_at":2017-10-01T14:20:35+08:00
}
查看某用户所有文章
curl -a https://api.example.com/zz/articles
成功
{
"username":"huangshim23"
"total_num":20,
"articles":[
{
"title":"title1",
"id": 1,
"href":" https://api.example.com/zz/articles/1",
"action":"GET",
"status":"original"
"created_time": "2010-11-11T17:31:50Z",
"updated_time": "2014-11-11T17:58:47Z",
"words": 3000,
"visits": 1000
},
{
//article2
},
{
//article3
}
...
]
}
发布文章
POST /user/articles
data //发布文章的数据参数
{
"title":
"content":
"description":
"visibility":
"status":
}
curl -u -p -d '{"title":"xxx","content":"xxx","description":"xxxx","visibility":true, "status": "orginal"}' https://api.example.com/zz/articles
成功
Status：200 OK
--------------------------
"isPublished":true ,
"article":{
"id": 13,
"title": "articleTitle",
"owner": {
"name": "zz",
"id": 123,
"url": "https://api.example.com/zz",
"type": "User"
},
"article_url": "https://api.example.com/zz/articles/13",
"private": false,
"description": "...",
"reading number": 19,
"created_at": "2016-11-11T17:31:50Z",
"words": 15022,
"content":"...."
}
}
删除文章
DELETE /user/articles/id
curl -d -i https://api.example.com/zz/articles/13
成功
Status：200 OK
--------------------------
{
"successed": "true",
"article_id": "13",
"deleted_at": "2019-11-20T10:30:50Z"
}
查看文章评论
GET /user/articles/id/comments
curl -u https://api.example.com/zz/articles/11/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
},
...
]
}
发布评论
curl -u -i https://api.example.com/zz/articles/3/comments -d {"contents":"xxx"}
成功
"contents":"xxx",
"comment_status": "succeeded",
"user": {
"id": 3,
"name":"user2"
"url": "xxx",
"type": "***",
"site_admin": false
},
"comment_time": "2019-12-12T00:00:00Z",