python

Django CMS API 文档

Y
小 明
|
|
79 次阅读
|
#django
Django CMS API 文档
Django CMS API 文档

Django CMS API 文档

概述

本文档描述了Django CMS系统的RESTful API接口。所有API端点都返回JSON格式的数据。

基础信息

  • Base URL: http://localhost:8000/api/
  • 认证方式: Session-based authentication
  • 数据格式: JSON
  • 编码: UTF-8

状态码

状态码 说明
200 请求成功
201 创建成功
400 请求参数错误
401 未认证
403 权限不足
404 资源不存在
500 服务器内部错误

通用响应格式

成功响应

JSON
{
    "success": true,
    "data": {},
    "message": "操作成功"
}

错误响应

JSON
{
    "success": false,
    "error": "错误类型",
    "message": "详细的错误信息"
}

文章相关API

获取文章列表

GET /api/articles/

查询参数

参数 类型 必需 说明
page integer 否 页码，默认1
page_size integer 否 每页数量，默认10
category integer 否 分类ID
tag integer 否 标签ID
search string 否 搜索关键词
status string 否 文章状态(draft/published/archived)

响应示例

JSON
{
    "success": true,
    "data": {
        "articles": [
            {
                "id": 1,
                "title": "文章标题",
                "slug": "article-title",
                "summary": "文章摘要",
                "content": "文章内容...",
                "author": {
                    "id": 1,
                    "username": "作者名"
                },
                "category": {
                    "id": 1,
                    "name": "分类名"
                },
                "tags": [
                    {"id": 1, "name": "标签1"},
                    {"id": 2, "name": "标签2"}
                ],
                "status": "published",
                "views_count": 100,
                "created_at": "2026-02-05T10:30:00Z",
                "updated_at": "2026-02-05T10:30:00Z",
                "published_at": "2026-02-05T10:30:00Z"
            }
        ],
        "pagination": {
            "current_page": 1,
            "total_pages": 5,
            "total_items": 47,
            "has_next": true,
            "has_previous": false
        }
    }
}

获取文章详情

GET /api/articles/{slug}/

响应示例

JSON
{
    "success": true,
    "data": {
        "id": 1,
        "title": "完整文章标题",
        "slug": "full-article-title",
        "summary": "文章摘要",
        "content": "完整的文章内容...",
        "author": {
            "id": 1,
            "username": "作者名",
            "avatar": "/media/avatars/avatar.jpg"
        },
        "category": {
            "id": 1,
            "name": "技术分享"
        },
        "tags": [
            {"id": 1, "name": "Django"},
            {"id": 2, "name": "Python"}
        ],
        "status": "published",
        "views_count": 150,
        "seo_title": "SEO标题",
        "seo_keywords": "关键词1,关键词2",
        "seo_description": "SEO描述",
        "created_at": "2026-02-05T10:30:00Z",
        "updated_at": "2026-02-05T10:30:00Z",
        "published_at": "2026-02-05T10:30:00Z"
    }
}

创建文章

POST /api/articles/create/

请求头

PLAINTEXT
Content-Type: application/json
X-CSRFToken: your_csrf_token

请求体

JSON
{
    "title": "新文章标题",
    "content": "文章内容",
    "summary": "文章摘要",
    "category": 1,
    "tags": ["标签1", "标签2"],
    "status": "draft",
    "seo_title": "SEO标题",
    "seo_keywords": "关键词1,关键词2",
    "seo_description": "SEO描述"
}

响应示例

JSON
{
    "success": true,
    "message": "文章创建成功",
    "data": {
        "id": 2,
        "title": "新文章标题",
        "slug": "xin-wen-zhang-biao-ti",
        "status": "draft"
    }
}

更新文章

PUT /api/articles/{slug}/

请求体

JSON
{
    "title": "更新后的标题",
    "content": "更新后的内容",
    "status": "published"
}

删除文章

DELETE /api/articles/{slug}/

响应示例

JSON
{
    "success": true,
    "message": "文章删除成功"
}

分类相关API

获取分类列表

GET /api/categories/

响应示例

JSON
{
    "success": true,
    "data": {
        "categories": [
            {
                "id": 1,
                "name": "技术分享",
                "slug": "technology",
                "parent_id": null,
                "article_count": 15
            },
            {
                "id": 2,
                "name": "生活随笔",
                "slug": "life",
                "parent_id": null,
                "article_count": 8
            }
        ]
    }
}

标签相关API

获取标签列表

GET /api/tags/

响应示例

JSON
{
    "success": true,
    "data": {
        "tags": [
            {
                "id": 1,
                "name": "Django",
                "slug": "django",
                "article_count": 12
            },
            {
                "id": 2,
                "name": "Python",
                "slug": "python",
                "article_count": 20
            }
        ]
    }
}

评论相关API

发表评论

POST /api/comments/

请求体

JSON
{
    "article_id": 1,
    "content": "这是我的评论内容",
    "parent_id": null
}

响应示例

JSON
{
    "success": true,
    "message": "评论发表成功",
    "data": {
        "id": 1,
        "content": "这是我的评论内容",
        "created_at": "2026-02-05T10:30:00Z"
    }
}

错误处理

常见错误响应

400 Bad Request

JSON
{
    "success": false,
    "error": "参数缺失",
    "message": "文章ID和评论内容不能为空"
}

401 Unauthorized

JSON
{
    "success": false,
    "error": "未认证",
    "message": "请先登录"
}

403 Forbidden

JSON
{
    "success": false,
    "error": "权限不足",
    "message": "您没有执行此操作的权限"
}

404 Not Found

JSON
{
    "success": false,
    "error": "资源不存在",
    "message": "找不到指定的文章"
}

500 Internal Server Error

JSON
{
    "success": false,
    "error": "服务器内部错误",
    "message": "抱歉，服务器遇到了一些问题，请稍后再试。"
}

认证说明

需要认证的API端点：
- 创建文章
- 更新文章
- 删除文章
- 发表评论

认证方式为Django的Session认证，需要在请求中包含有效的CSRF Token。

示例代码

JavaScript/Fetch 示例

JAVASCRIPT
// 获取文章列表
fetch('/api/articles/')
    .then(response => response.json())
    .then(data => {
        if (data.success) {
            console.log('文章列表:', data.data.articles);
        }
    });

// 创建文章
fetch('/api/articles/create/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-CSRFToken': getCookie('csrftoken')
    },
    body: JSON.stringify({
        title: '新文章',
        content: '文章内容',
        status: 'draft'
    })
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        console.log('文章创建成功:', data.data);
    }
});

Python/requests 示例

PYTHON
import requests

# 获取文章列表
response = requests.get('http://localhost:8000/api/articles/')
data = response.json()
if data['success']:
    articles = data['data']['articles']
    print(f"获取到 {len(articles)} 篇文章")

# 创建文章
headers = {
    'Content-Type': 'application/json',
    'X-CSRFToken': 'your_csrf_token'
}
article_data = {
    'title': '新文章',
    'content': '文章内容',
    'status': 'draft'
}
response = requests.post(
    'http://localhost:8000/api/articles/create/',
    json=article_data,
    headers=headers
)
data = response.json()
if data['success']:
    print(f"文章创建成功，ID: {data['data']['id']}")

版本历史

  • v1.0 (2026-02-05): 初始版本，包含基础的CRUD操作

评论 (0)

登录后才能发表评论

登录发表评论
#django
返回列表