update
This commit is contained in:
Iliyan Angelov
213
backEnd/blog/README.md
Normal file
213
backEnd/blog/README.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user