# Blog API Documentation

This document provides information about the Blog API implementation for the GNX Software Solutions website.

## Overview

The Blog API is a RESTful API built with Django REST Framework that provides endpoints for managing blog posts, categories, authors, tags, and comments.

## Backend Setup

### Models

The blog app includes the following models:

1. **BlogAuthor** - Stores information about blog post authors
2. **BlogCategory** - Categories for organizing blog posts
3. **BlogTag** - Tags for additional post categorization
4. **BlogPost** - The main blog post model
5. **BlogComment** - Comments on blog posts (with moderation support)

### API Endpoints

Base URL: `/api/blog/`

#### Blog Posts

- `GET /api/blog/posts/` - List all blog posts (with pagination and filtering)
  - Query parameters:
    - `category` - Filter by category slug
    - `tag` - Filter by tag slug
    - `author` - Filter by author ID
    - `search` - Search in title, content, and excerpt
    - `featured` - Filter featured posts
    - `ordering` - Sort by fields (e.g., `-published_at`, `views_count`)
    - `page` - Page number
    - `page_size` - Items per page (default: 9)

- `GET /api/blog/posts/{slug}/` - Get a single blog post by slug
- `GET /api/blog/posts/featured/` - Get featured blog posts
- `GET /api/blog/posts/latest/?limit=5` - Get latest blog posts
- `GET /api/blog/posts/popular/?limit=5` - Get popular posts by views
- `GET /api/blog/posts/{id}/related/` - Get related posts

#### Categories

- `GET /api/blog/categories/` - List all categories
- `GET /api/blog/categories/{slug}/` - Get a single category by slug
- `GET /api/blog/categories/with_posts/` - Get categories that have published posts

#### Authors

- `GET /api/blog/authors/` - List all authors
- `GET /api/blog/authors/{id}/` - Get a single author
- `GET /api/blog/authors/{id}/posts/` - Get all posts by an author

#### Tags

- `GET /api/blog/tags/` - List all tags
- `GET /api/blog/tags/{slug}/` - Get a single tag by slug
- `GET /api/blog/tags/{slug}/posts/` - Get all posts with a specific tag

#### Comments

- `GET /api/blog/comments/?post={post_id}` - Get comments for a post
- `POST /api/blog/comments/` - Create a new comment (requires moderation)

### Management Commands

#### Populate Blog Data

To populate the database with sample blog data:

```bash
python manage.py populate_blog
```

This command creates:
- 4 sample authors
- 6 blog categories
- 16 tags
- 8 sample blog posts with full content

## Frontend Integration

### API Service

Location: `/lib/api/blogService.ts`

The service provides functions for:
- Fetching blog posts (with filtering)
- Getting single posts by slug
- Fetching categories, tags, and authors
- Getting featured, latest, and popular posts
- Managing comments

### Custom Hooks

Location: `/lib/hooks/useBlog.ts`

Available hooks:
- `useBlogPosts(params)` - Fetch paginated list of posts
- `useBlogPost(slug)` - Fetch a single post
- `useFeaturedPosts()` - Fetch featured posts
- `useLatestPosts(limit)` - Fetch latest posts
- `usePopularPosts(limit)` - Fetch popular posts
- `useBlogCategories()` - Fetch all categories
- `useBlogTags()` - Fetch all tags
- `useBlogAuthors()` - Fetch all authors

### Components

The following components have been updated to use the API:

1. **PostFilterButtons** - Fetches categories from API
2. **PostFilterItems** - Fetches and filters blog posts by category
3. **BlogSingle** - Fetches individual post by slug from URL params
4. **LatestPost** - Fetches latest posts for the slider

### Usage Examples

#### Fetching All Posts

```typescript
const { posts, loading, error, pagination } = useBlogPosts({
  category: 'enterprise-software',
  page_size: 9
});
```

#### Fetching a Single Post

```typescript
const { post, loading, error } = useBlogPost('api-first-approach-to-system-integration');
```

#### Fetching Latest Posts

```typescript
const { posts, loading, error } = useLatestPosts(5);
```

## Features

### Backend Features

1. **Pagination** - All list endpoints support pagination
2. **Filtering** - Filter posts by category, tag, author, and search
3. **Ordering** - Sort posts by date, views, etc.
4. **View Tracking** - Automatically increment view count when a post is viewed
5. **Related Posts** - Automatically suggest related posts from the same category
6. **Comment Moderation** - Comments require approval before being visible
7. **SEO Support** - Meta descriptions and keywords for each post
8. **Reading Time** - Estimated reading time for posts
9. **Tags System** - Flexible tagging for better categorization

### Frontend Features

1. **Real-time Data** - All data fetched from API
2. **Loading States** - Proper loading indicators
3. **Error Handling** - Graceful error handling with fallbacks
4. **Image Optimization** - Uses Next.js Image component
5. **Responsive Design** - Mobile-friendly layouts
6. **Category Filtering** - Filter posts by category with smooth animations
7. **Social Sharing** - Share posts on social media
8. **Related Posts** - Automatically shows related posts
9. **SEO Friendly** - Proper meta tags and structured data

## Sample Data

The populated sample data includes:

### Categories
- Enterprise Software
- Digital Transformation
- System Integration
- Cloud Solutions
- Security
- API Development

### Sample Post Topics
1. The Future of Enterprise Software Architecture
2. Digital Transformation Strategies for Large Enterprises
3. API-First Approach to System Integration
4. Cloud Migration Best Practices for Enterprise
5. Enterprise Security in the Digital Age
6. Building Scalable API Architectures
7. Microservices Architecture for Enterprise Applications
8. Data Analytics and Business Intelligence Solutions

## Notes

- All blog posts support HTML content
- Images can be uploaded or linked via URL
- Posts can be marked as featured
- Comments require moderation before being visible
- The API respects published status (unpublished posts are not returned)
- View counts are automatically tracked
- Related posts are determined by category

## Future Enhancements

Potential improvements:
1. Add full-text search using Elasticsearch
2. Implement post series/collections
3. Add newsletter subscription functionality
4. Implement post scheduling
5. Add analytics dashboard
6. Support for multiple authors per post
7. Rich text editor in admin
8. Image upload and management
9. Post translations/i18n support
10. RSS feed generation