Skip to content

api-reference.md

Latest commit

 

History

History
254 lines (219 loc) · 3.83 KB

api-reference.md

File metadata and controls

254 lines (219 loc) · 3.83 KB

📚 MapleCMS API Reference

MapleCMS exposes a clean, RESTful API built with FastAPI, designed to be fast, secure, and easy to integrate with any frontend or external service.
This document outlines all key endpoints, authentication methods, and data schemas.

🧠 Overview

  • Base URL (Local): http://localhost:8000/api/v1
  • Base URL (Production): https://api.maplecms.com/api/v1
  • Format: JSON (application/json)
  • Authentication: JWT Bearer Token

🔐 Authentication

Login

POST /auth/login

{
  "email": "user@example.com",
  "password": "password123"
}

Response:

{
  "access_token": "<JWT_TOKEN>",
  "token_type": "bearer",
  "expires_in": 3600
}

Register

POST /auth/register

{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "strongpassword"
}

Response:

{
  "message": "User registered successfully",
  "user_id": 12
}

Refresh Token

POST /auth/refresh

{
  "refresh_token": "<REFRESH_TOKEN>"
}

Response:

{
  "access_token": "<NEW_JWT_TOKEN>"
}

📝 Articles

Get All Articles

GET /articles/ Response:

[
  {
    "id": 1,
    "title": "Welcome to MapleCMS",
    "slug": "welcome-maplecms",
    "author": "Admin",
    "tags": ["intro", "cms"],
    "created_at": "2025-01-05T10:30:00Z"
  }
]

Get Article by ID

GET /articles/{id} Response:

{
  "id": 1,
  "title": "Welcome to MapleCMS",
  "content": "<html>Article body here...</html>",
  "author": "Admin",
  "category": "Tutorial",
  "published": true
}

Create Article

POST /articles/ Auth Required ✅

{
  "title": "My New Article",
  "content": "MapleCMS makes content creation simple!",
  "tags": ["fastapi", "nextjs"],
  "category": "Development",
  "published": true
}

Response:

{
  "id": 22,
  "message": "Article created successfully"
}

Update Article

PUT /articles/{id}

{
  "title": "Updated Title",
  "content": "Updated content..."
}

Response:

{
  "message": "Article updated"
}

Delete Article

DELETE /articles/{id} Response:

{
  "message": "Article deleted successfully"
}

🧩 Media

Upload File

POST /media/upload

  • Type: multipart/form-data
curl -X POST -F "file=@/path/to/image.png" https://api.maplecms.com/api/v1/media/upload

Response:

{
  "file_url": "https://cdn.maplecms.com/uploads/image.png"
}

List Files

GET /media/ Response:

[
  {"filename": "image.png", "url": "https://cdn.maplecms.com/uploads/image.png"}
]

👥 Users

Get Profile

GET /users/me Auth Required ✅ Response:

{
  "id": 5,
  "username": "john_doe",
  "email": "john@example.com",
  "role": "editor"
}

List Users (Admin only)

GET /users/ Response:

[
  {"id": 1, "username": "admin"},
  {"id": 2, "username": "editor"}
]

🧱 Categories & Tags

Get All Categories

GET /categories/

[
  {"id": 1, "name": "Tutorials"},
  {"id": 2, "name": "Guides"}
]

Create Category

POST /categories/

{
  "name": "AI"
}

Response:

{
  "message": "Category created"
}

⚙️ System & Meta Endpoints

Health Check

GET /health

{
  "status": "ok",
  "uptime": "3 days, 12 hours"
}

API Version

GET /version

{
  "version": "1.0.0",
  "build": "2025-01-07T10:00:00Z"
}

🧭 Notes

  • All endpoints are CORS-enabled for integration with the Next.js frontend.
  • Rate limiting and caching can be enabled in production.
  • Future versions will include GraphQL and WebSocket endpoints.

MapleCMS API — built to be lightweight, scalable, and developer-friendly.