214 lines
6.3 KiB
Markdown
214 lines
6.3 KiB
Markdown
# 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
|
|
|