Chirpy is a robust, production-ready microblogging API built with Go that provides Twitter-like functionality. It features user authentication, content management, real-time metrics, and premium user upgrades through webhook integrations.
Chirpy is a RESTful API that enables users to:
- Create and manage user accounts with secure authentication
- Post short messages (chirps) with content filtering and validation
- Authenticate users using JWT tokens with refresh token support
- Manage user profiles with email and password updates
- Upgrade to premium features through webhook integrations
- Track application metrics with admin dashboard
- Serve static content with hit tracking
- Production Ready: Built with enterprise-grade security and scalability in mind
- Modern Architecture: Uses Go 1.24.4 with PostgreSQL and JWT authentication
- Content Safety: Built-in profanity filtering and content validation
- Developer Friendly: Comprehensive API documentation and easy setup
- Extensible: Modular design with clear separation of concerns
- Monitoring: Built-in metrics and health checks for production deployment
- Backend: Go 1.24.4
- Database: PostgreSQL
- Authentication: JWT with refresh tokens
- Password Hashing: bcrypt
- Database ORM: sqlc (type-safe SQL)
- Environment: godotenv
- UUID Generation: Google UUID
Before running Chirpy, ensure you have:
- Go 1.24.4 or later installed
- PostgreSQL database server running
- Git for cloning the repository
git clone https://github.com/frozendolphin/Chirpy.git
cd Chirpygo mod downloadCREATE DATABASE chirpy_db;The project uses Goose for database migrations. Install Goose first:
go install github.com/pressly/goose/v3/cmd/goose@latestThen run the migrations:
goose -dir sql/schema postgres "your_connection_string" upCreate a .env file in the project root:
DB_URL=postgres://username:password@localhost:5432/chirpy_db?sslmode=disable
PLATFORM=dev
SECRET=your_jwt_secret_key_here
POLKA_KEY=your_polka_webhook_key_here //polka is just like stripeThe project uses sqlc for type-safe database operations:
sqlc generatego run .The server will start on http://localhost:8080
Create a new user account.
Request Body:
{
"email": "[email protected]",
"password": "securepassword"
}Response:
{
"id": "uuid",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"email": "[email protected]",
"is_chirpy_red": false
}Authenticate a user and receive access tokens.
Request Body:
{
"email": "[email protected]",
"password": "securepassword"
}Response:
{
"id": "uuid",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"email": "[email protected]",
"token": "jwt_access_token",
"refresh_token": "jwt_refresh_token",
"is_chirpy_red": false
}Refresh an access token using a refresh token.
Headers:
Authorization: Bearer <refresh_token>
Response:
{
"token": "new_jwt_access_token"
}Revoke a refresh token.
Headers:
Authorization: Bearer <refresh_token>
Create a new chirp (post).
Headers:
Authorization: Bearer <access_token>
Request Body:
{
"body": "This is my chirp content!"
}Response:
{
"id": "uuid",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"body": "This is my chirp content!",
"user_id": "uuid"
}Retrieve all chirps.
Response:
[
{
"id": "uuid",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"body": "This is my chirp content!",
"user_id": "uuid"
}
]Retrieve a specific chirp by ID.
Delete a specific chirp (requires authentication).
Headers:
Authorization: Bearer <access_token>
Update user email and password.
Headers:
Authorization: Bearer <access_token>
Request Body:
{
"email": "[email protected]",
"password": "newpassword"
}View application metrics (hit counter).
Response:
<html>
<body>
<h1>Welcome, Chirpy Admin</h1>
<p>Chirpy has been visited 42 times!</p>
</body>
</html>Reset all users (development only).
Handle Polka webhook events for user upgrades.
Headers:
Authorization: ApiKey <polka_key>
Request Body:
{
"event": "user.upgraded",
"data": {
"user_id": "uuid"
}
}Health check endpoint.
Serve static files with hit tracking.
- JWT Authentication: Secure token-based authentication
- Password Hashing: bcrypt for secure password storage
- Content Filtering: Automatic profanity filtering
- Input Validation: Comprehensive request validation
- CORS Support: Cross-origin resource sharing configuration
- Rate Limiting: Built-in request limiting (configurable)
Chirpy automatically filters inappropriate content by replacing profane words with asterisks. The current filter list includes:
- kerfuffle
- sharbert
- fornax
Chirpy/
├── main.go # Application entry point
├── handlechirps.go # Chirp-related handlers
├── handleusers.go # User management handlers
├── handlelogin.go # Authentication handlers
├── handlerefresh.go # Token refresh handlers
├── handlewebhook.go # Webhook handlers
├── metrics.go # Metrics and monitoring
├── readiness.go # Health checks
├── json.go # JSON response utilities
├── go.mod # Go module dependencies
├── sqlc.yaml # SQL code generation config
├── test.http # API testing examples
├── internal/
│ ├── auth/ # Authentication utilities
│ └── database/ # Generated database code
├── sql/
│ ├── schema/ # Database migrations
│ └── queries/ # SQL queries
└── assets/ # Static assets
Test the API using the provided test.http file or with curl:
# Test health endpoint
curl http://localhost:8080/api/healthz
# Create a user
curl -X POST http://localhost:8080/api/users \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","password":"password123"}'- Environment Variables: Ensure all required environment variables are set
- Database: Use a production PostgreSQL instance
- SSL/TLS: Configure HTTPS for production
- Monitoring: Set up proper logging and monitoring
- Backup: Implement database backup strategies
This project is licensed under the MIT License - see the LICENSE file for details.
- Uses sqlc for type-safe database operations
- JWT implementation for secure authentication
- PostgreSQL for reliable data storage
For support, please open an issue on GitHub.