API Documentation Overview

AstrNest provides a comprehensive RESTful API interface supporting image upload, management, user authentication, and more. All APIs follow REST design principles and use JSON format for data exchange.

🔑 Authentication Methods

1. JWT Token Authentication (Recommended)

For web frontend and mobile applications:

Authorization: Bearer <jwt-token>

Get Token:

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "chenxi123"
}

2. API Key Authentication

For third-party application integration:

X-API-Key: <api-key>

Get API Key:

1. Login to admin interface
2. Navigate to "API Key Management"
3. Create new API key

📊 Response Format

Success Response

{
  "code": 200,
  "message": "Operation successful",
  "data": {
    "id": 1,
    "name": "Example Data"
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

Error Response

{
  "code": 400,
  "message": "Request parameter error",
  "error": "Detailed error message",
  "timestamp": "2024-01-01T00:00:00Z"
}

📋 Status Code Reference

Status Code	Description
200	Request successful
201	Created successfully
400	Request parameter error
401	Unauthorized
403	Insufficient permissions
404	Resource not found
429	Rate limit exceeded
500	Internal server error

🔌 API Categories

User-related APIs

• Authentication: Login, registration, captcha
• User Information: Profile, security settings
• Upload Management: Image upload, view, delete

Management APIs

• User Management: User list, role management
• Content Management: Upload records, content moderation
• System Configuration: System parameters, email configuration

Public APIs

• Public Gallery: Public image browsing
• Visitor Features: Likes, user information

🚀 Quick Start

1. Get Access Token

curl -X POST "http://localhost:8080/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "chenxi123"
  }'

Response:

{
  "code": 200,
  "message": "Login successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "admin",
      "role": "ADMIN"
    }
  }
}

2. Use Token to Call API

curl -X GET "http://localhost:8080/api/user/profile" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

📝 Pagination

All list APIs support pagination:

GET /api/user/uploads?page=1&size=20&sort=createdAt,desc

Response format:

{
  "content": [
    // Data list
  ],
  "totalElements": 100,
  "totalPages": 5,
  "size": 20,
  "number": 0,
  "first": true,
  "last": false
}

🔒 Permission Control

Different roles have different API access permissions:

Role	Permission Description
ADMIN	All API permissions
USER	User-related APIs
VISITOR	Read-only APIs

📡 Live Documentation

Access Swagger UI for complete API documentation:

http://localhost:8080/swagger-ui.html

🧪 Testing Tools

Using Postman

1. Import Postman collection
2. Set environment variables
3. Call login API to get token
4. Use token to test other APIs

Using curl

# Set environment variables
export TOKEN="your-jwt-token"
export BASE_URL="http://localhost:8080"

# Test user info API
curl -H "Authorization: Bearer $TOKEN" "$BASE_URL/api/user/profile"

⚠️ Important Notes

1. Rate Limiting: API calls are rate limited, avoid frequent requests
2. Parameter Validation: All parameters are strictly validated
3. Error Handling: Handle various error scenarios properly
4. Version Control: API versions will be updated with project releases
5. Data Security: Sensitive data requires encrypted transmission

📚 Detailed API Documentation

• API Overview - Complete API reference
• User Management API - User authentication and management
• File Upload API - File upload and management

🔄 Changelog

v1.0.0 (2024-01-01)

• Initial version release
• Complete RESTful API interface
• JWT and API Key dual authentication
• Comprehensive error handling mechanism

---

🔗 Related Links: Quick Start | Project Introduction | FAQ