2019-11-20

博客网站REST API设计

本文总阅读量次

主要功能：

用户注册

Request

1
POST /api/v1/users

Input

name type description
username string name of the signing user
password string password
captchaID string ID of the captcha
captchaCode string Code of the identifaction 
1
2
3
4
5
6
7
{
	"username": "Zhangqzh"
	"password": "Zhangqzh",
	"captcha_id": "You have got a captcha ID",
	"captcha_code": "Response",
	"created_at": "2019-11-20T00:00:00Z"
}

Response

1
2
3
Status: 201 Created

Location: /api/v1/users
1
2
3
4
5
{
  "id": 1
  "user_name": "Zhangqzh",
  "created_at": "2019-11-20T00:00:00Z"
}

用户登陆

Request

1
POST /api/v1/users/login

Input

name type description
username string name of the signing user
password string password
captchaID string ID of the captcha
captchaCode string Code of the identifaction 
1
2
3
4
5
6
7
8
{
	"username": "Zhangqzh"
	"password": "Zhangqzh",
	"captcha_id": "You have got a captcha ID",
	"captcha_code": "Response",
	"created_at": "2019-11-20T00:00:00Z"
	"updated_at": "2019-11-20T01:00:00Z"
}

Response

1
2
3
Status: 201 OK

Location: /api/v1/users
1
2
3
4
{
	"access_token": "token...",
	"expires_in": 3600
}

Failed login limit

验证无效的凭据将返回401未经授权:
curl -i https://api.blog.com -u foo:bar 

1
2
3
4
5
HTTP/1.1 401 Unauthorized
{
  "message": "Bad credentials",
  "documentation_url": "https://developer.blog.com/v3"
}

在短时间内检测到几个证书无效的请求后，API将暂时拒绝该用户的所有身份验证尝试(包括有效证书)，403禁止

curl -i https://api.blog.com -u valid_username:valid_password 

1
2
3
4
5
6
7
8
9
10
11
HTTP/1.1 403 Forbidden
{
  "message": "Maximum number of login attempts exceeded. Please try again later.",
  "documentation_url": "https://developer.blog.com/v3"
}
```  
## <span id = "getca">获取分类列表</span>  
### Request

```bash
GET /api/v1/categories

Input

name type description
page number page number
size number size of page

Response

1
2
Status: 200 OK
Location: /api/v1/categories
1
2
3
4
5
6
7
8
9
{
 "categories"[
{
	"id": "0", 
	"node_id": "MDEwOlJlcG9zaXRvcnkxOTE0MzIzMjE=",
    "category_name": "Go语言学习", 
    "article_count": 10 
}]
}

创建分类列表

Request

POST /api/v1/categories

Input

name type description
name strinf name of category

{
“name”: “3D unity”
}

Response

1
2
3
4
5
6
7
8
9
10
Status: 201 Created
Location: /api/v1/categories
```  

```javascript

{
    "id": 1,
    "name": "3D unity"
}

注意：必须添加权限验证,否则返回401 Unauthorized

更新分类列表

Request

PUT /api/v1/categories/:category_id

Input

name type description
category_name string name of category 
1
2
3
{
    "name": "3D unity"
}

Response

1
2
Status: 200 OK
Location: /api/v1/categories/0
1
2
3
4
5
6
{
    "id": 1,
    "name": "3D unity"
    "message": "update from ",
    "content": "Y3JlYXRlIGZpbGUgZnJvbSBJTlNPTU5JQQoKSXQncyB1cGRhdGVkISEhCgpJdCdzIHVwZGF0ZWQgYWdhaW4hIQ==",
}

注意：必须添加权限验证,否则返回401 Unauthorized

删除分类

Request

DELETE /api/v1/categories:category_id

Input

name type description
category_name string name of category 
1
2
3
{
    "name": "3D unity"
}

Response

1
2
Status: 204 No Content
Location: /api/v1/categories/0
1
2
3
{
  "message": "delete a category",
}

注意：必须添加权限验证,否则返回401 Unauthorized

获取分类内的文章

Request

GET /api/v1/categories/:category_id

Input

name type description
page number page number
size number size of page

Response

1
2
Status: 200 OK
Location: /api/v1/categories/0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "category": "Go 语言学习",
    "articles": [
        {
            "id": 0,
            "title": "源码学习-net/http",
            "created_at": "2019-11-11T00:00:00Z"
        },
        {
            "id": 1,
            "title": "阅读《Golang web应用开发》",
            "created_at": "2019-11-05T00:00:00Z"
        }
    ]
    ...
}

获取某个文章

Request

GET /api/v1/articles/:article_id

Response

1
2
Status: 200 OK
Location: /api/v1/articles/0
1
2
3
4
5
6
7
{
    "id": 0,
    "category_id": 0,
    "category_name": "Go 语言学习",
    "article_title": "源码学习-net/http",
    "article_content": "*****"
}

创建新文章

Request

POST /api/v1/articles

Input

name type description
catagory_id number id of category
article_title string title of article
content string content of article 
1
2
3
4
5
6
{
    "category_id": 0,
    "article_id": 2,
    "title": "博客网站REST API设计",
    "content": "*****"
}

Response

1
2
Status: 201 Created
Location: /api/v1/articles
1
2
3
4
5
6
7
8
9
{
    "categoryId": 0,
    "article_id": 2,
    "title": "博客网站REST API设计",
    "content": "*****"
    "size" : "*****"
    "created_at":"2019-11-20T00:00:00Z"
    "url": "https://api.blog.com/repos/go-"
}

注意：1. 必须添加权限验证,否则返回401 Unauthorized 2. 数据传送格式选择JSON 3. 文件内容必须是把文件整体转为Base64字符串再存到JSON变量中

更新文章

Request

PUT /api/v1/articles/:article_id

Input

name type description
catagory_id number id of category
article_title string title of article
content string content of article 
1
2
3
4
5
6
{
    "category_id": 0,
    "article_id": 2,
    "title": "博客网站REST API设计",
    "content": "*****"
}

Response

1
2
Status: 200 OK
Location: /api/v1/articles/3
1
2
3
4
5
6
7
8
9
10
{
    "categoryId": 0,
    "article_id": 2,
    "title": "博客网站REST API设计",
    "content": "*****"
    "size" : "*****"
    "created_at":"2019-11-20T00:00:00Z"
    "updated_at":"2019-11-20T14:00:00Z"
    "url": "https://api.blog.com/repos/go-"
}

注意：必须添加权限验证,否则返回401 Unauthorized
对文件格式有要求，如果没有按照格式把上传时的json必填项输入，则会出现422错误信息：

1
2
3
4
{   
    "message": "Invalid request...",
    "url": "https://api.blog.com/repos/go-"
}

删除文章

Request

DELETE /api/v1/articles/:article_id

1
2
3
{   
    "message": "delete a file",
}

Response

1
2
Status: 204 No Content
Location: /api/v1/articles/1
1
2
3
4
{   
    "content": null,
    "url": "https://api.blog.com/repos/go-"
}

获取文章的评论

Request

GET /api/v1/articles/:article_id/comments

Input

name type description
page number page number
size number size of page

Response

1
2
Status: 200 OK
Location: /api/v1/articles/
1
2
3
4
5
6
7
8
9
{
    "id": "0",
    "user": {
        "id": 0,
        "username": "zz",
    },
    "content": "*****",
    "created_at": "2019-11-20T00:00:00Z"
},

添加评论

Request

POST /api/v1/articles/:article_id/comments

Input

name type description
content string content 
1
2
3
{
    "content": "*****"
}

Response

1
2
Status: 202 Accepted
Location: /api/v1/articles/0/comments
1
2
3
4
5
6
{
    "id": "0",
    "article_title": "博客网站REST API设计"
    "content": "*****",
    "createdAt": "2019-11-19T00:00:00Z"
}
Rica Zhang

Rica Zhang

Hello, World!