Overview

Introduction

Aether CMS provides a comprehensive RESTful API that enables developers to manage content, media, themes, users, and static site generation programmatically. Built on the LiteNode framework, the API follows REST conventions and returns JSON responses for all endpoints.

API Architecture

Aether API is organized into several main modules:

• Content API - Manage posts, pages, and site settings
• Media API - Handle file uploads, metadata, and references
• Theme API - Install, configure, and manage themes
• User API - User authentication and management
• Static Site Generation API - Generate static versions of your site

Base URL Structure

All API endpoints are prefixed with /api/:

https://your-site.com/api/{endpoint}

Request/Response Format

Request Format

• Content-Type: application/json for most endpoints
• Content-Type: multipart/form-data for file uploads
• Method: GET, POST, PUT, DELETE as appropriate

Response Format

All API responses follow a consistent structure:

{
  "success": true|false,
  "data": {}, // Response data (varies by endpoint)
  "error": "Error message", // Only present on errors
  "message": "Additional info" // Optional descriptive message
}

Success Response Example

{
    "success": true,
    "data": {
        "id": "123456789",
        "title": "My Blog Post",
        "status": "published"
    }
}

Error Response Example

{
    "success": false,
    "error": "Post not found",
    "message": "The requested post could not be located"
}

HTTP Status Codes

The API uses standard HTTP status codes:

• 200 OK - Request successful
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Authentication required
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 409 Conflict - Resource conflict (e.g., duplicate slug)
• 500 Internal Server Error - Server error

Authentication Overview

All API endpoints require authentication except for public content endpoints. The API supports:

• Bearer Token Authentication - Primary method for API access
• Session Cookie Authentication - For web interface integration

Content Types

The API works with several content types:

Posts

Blog posts and articles with:

• Metadata (title, slug, author, dates)
• Content (Markdown format)
• Categories and tags
• Featured images
• Related posts

Pages

Static pages with:

• Metadata and content
• Page types (normal/custom)
• Parent-child relationships
• Custom templates

Media

File management including:

• Images and documents
• Metadata (alt text, captions)
• Reference tracking
• Automatic optimization

Query Parameters

Many endpoints support query parameters for filtering and pagination:

Common Parameters

• status - Filter by publication status
• limit - Limit number of results
• offset - Skip number of results
• frontmatterOnly - Return only metadata
• properties - Select specific fields

Example

GET /api/posts?status=published&limit=10&frontmatterOnly=true&properties=id,title,slug

Extensibility

The API includes a hook system for customization:

Filters

Modify data before it's returned:

hookSystem.addFilter("api_posts", (posts, req) => {
    // Modify posts array
    return posts
})

Actions

Execute code at specific points:

hookSystem.doAction("post_created", postData)

API Versioning

The current API version is embedded in the endpoint structure. Future versions will maintain backward compatibility or provide migration paths.

Rate Limiting

The API includes built-in rate limiting to prevent abuse:

• Login attempts are limited (5 attempts per 15 minutes)
• Other endpoints may have limits based on user role
• Rate limit headers are included in responses

Development vs Production

Development Features

• Detailed error messages
• Request logging
• Debug information

Production Features

• Enhanced security headers
• Error message sanitization
• Performance optimizations

Getting Started

1. Obtain API credentials - Login to get an authentication token
2. Test connectivity - Make a simple GET request to verify access
3. Explore endpoints - Use the detailed API documentation for each module
4. Implement error handling - Always check the success field in responses
5. Respect rate limits - Implement appropriate delays between requests

SDK and Tools

While no official SDK exists, the API is designed to work with:

• Standard HTTP libraries (fetch, axios, curl)
• API testing tools (Postman, Insomnia)
• Custom JavaScript applications
• Static site generators