Introduction
Imagine you're building a travel app, a cultural education platform, or a smart assistant that helps people discover festivals worldwide. You need accurate data about Diwali in India, Carnival in Brazil, Thanksgiving in the US, or the Cherry Blossom Festival in Japan. But more than dates and names, you need context—historical significance, kid-friendly explanations, travel tips, and compelling summaries that make each event come alive.
That's exactly why I built FestiFlow AI.
What I Built?
Overview
FestiFlow AI is a comprehensive REST API that serves as a knowledge base for global cultural events. It combines structured data about festivals, holidays, and cultural observances with dynamically generated AI insights that bring each event to life.
List of APIs -
AI generated database and tables -
Types of Data Provided
Core Festival Data:
- Festival names and alternative names
- Accurate dates (with recurring date patterns)
- Country associations
- Detailed descriptions
- Cultural and historical significance
- Celebration customs and traditions
- Type classifications (religious, cultural, national, seasonal)
AI-Generated Enrichment:
- Concise 3-sentence summaries perfect for cards and listings
- Kid-friendly explanations that make complex traditions accessible
- Historical timelines showing the evolution of celebrations
- Practical travel advice for tourists attending the events
- Cultural context and modern relevance
API Documentation
Authentication
FestiFlow AI uses API key authentication to protect resources and enable usage tracking.
API Key Types:
| Type | Purpose | Capabilities |
|---|---|---|
| Public Key | General API access | Read festivals, countries; Generate AI data |
| Admin Key | Content management | All public capabilities + Create/update festivals |
Including Your API Key:
All requests must include your API key in the X-API-Key header:
X-API-Key: your_api_key_here
Getting an API Key:
Public API keys are available through the developer portal. Contact the administrator for admin-level access.
Rate Limiting
To ensure fair usage and system stability, FestiFlow AI implements the following limits:
| Limit Type | Value | Description |
|---|---|---|
| Daily Limit | 100 requests/day | Total requests per API key per 24-hour period |
| Burst Limit | 10 requests/second | Maximum concurrent request rate |
Rate Limit Headers:
Every response includes these headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1733270400
Exceeding Limits:
When limits are exceeded, you'll receive a 429 Too Many Requests response:
{
"error": "Rate limit exceeded",
"message": "You have exceeded your daily request limit of 100 requests",
"retry_after": 3600
}
Endpoints
1. GET /country
Retrieve a list of all countries with festival data.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
page |
integer | No | Page number (default: 1) |
per_page |
integer | No | Items per page (default: 50, max: 100) |
Example Request:
curl -X GET "https://api.festiflow.com/v1/countries?page=1&per_page=20" \
-H "X-API-Key: your_api_key_here"
Example Response:
{
"data": [
{
"id": 1,
"name": "India",
"code": "IN",
"festival_count": 47
},
{
"id": 2,
"name": "United States",
"code": "US",
"festival_count": 32
},
{
"id": 3,
"name": "Japan",
"code": "JP",
"festival_count": 28
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total_items": 156,
"total_pages": 8
}
}
2. GET /festival
Retrieve festivals with optional filtering.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
country_id |
integer | No | Filter by country ID |
month |
integer | No | Filter by month (1-12) |
name |
string | No | Search by festival name (partial match) |
include_ai_data |
boolean | No | Include AI-generated enrichment (default: false) |
page |
integer | No | Page number (default: 1) |
per_page |
integer | No | Items per page (default: 20, max: 100) |
Example Request:
curl -X GET "https://api.festiflow.com/v1/festivals?country_id=1&month=10&include_ai_data=true" \
-H "X-API-Key: your_api_key_here"
Example Response (with AI data):
{
"data": [
{
"id": 101,
"name": "Diwali",
"alternative_names": ["Deepavali", "Festival of Lights"],
"country": {
"id": 1,
"name": "India",
"code": "IN"
},
"date": "2025-10-23",
"month": 10,
"type": "religious",
"description": "Diwali is one of the most important festivals in Hinduism, celebrating the victory of light over darkness and good over evil.",
"significance": "Commemorates Lord Rama's return to Ayodhya after defeating Ravana. Symbolizes the triumph of knowledge over ignorance.",
"traditions": [
"Lighting oil lamps (diyas)",
"Fireworks displays",
"Exchanging gifts and sweets",
"Decorating homes with rangoli",
"Worship of Goddess Lakshmi"
],
"ai_enrichment": {
"summary": "Diwali, the Hindu Festival of Lights, celebrates the triumph of good over evil through five days of lamp lighting, fireworks, and family gatherings.",
"kid_friendly_explanation": "Diwali is like a giant birthday party for light! Families light thousands of little oil lamps and colorful candles to celebrate good things winning over bad things. Everyone wears new clothes, eats yummy sweets, and watches beautiful fireworks light up the night sky.",
"travel_advice": "Plan to visit major cities like Jaipur, Varanasi, or Amritsar during Diwali for spectacular celebrations, but book accommodations months in advance as this is peak tourist season. Bring earplugs if you're sensitive to noise, as fireworks continue late into the night. Participate respectfully by wearing traditional Indian clothing if invited to celebrations, and always accept offered sweets with your right hand. The best photo opportunities come just after sunset when millions of lamps are lit simultaneously."
},
"has_ai_data": true,
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-11-20T14:45:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total_items": 12,
"total_pages": 1
}
}
3. GET /festival/{festival_id}
Retrieve a specific festival by ID.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
integer | Yes | Festival ID (in URL path) |
include_ai_data |
boolean | No | Include AI-generated enrichment (default: false) |
Example Request:
curl -X GET "https://api.festiflow.com/v1/festivals/101?include_ai_data=true" \
-H "X-API-Key: your_api_key_here"
Example Response:
{
"data": {
"id": 101,
"name": "Diwali",
"alternative_names": ["Deepavali", "Festival of Lights"],
"country": {
"id": 1,
"name": "India",
"code": "IN"
},
"date": "2025-10-23",
"month": 10,
"type": "religious",
"description": "Diwali is one of the most important festivals in Hinduism, celebrating the victory of light over darkness and good over evil.",
"significance": "Commemorates Lord Rama's return to Ayodhya after defeating Ravana. Symbolizes the triumph of knowledge over ignorance.",
"traditions": [
"Lighting oil lamps (diyas)",
"Fireworks displays",
"Exchanging gifts and sweets",
"Decorating homes with rangoli",
"Worship of Goddess Lakshmi"
],
"ai_enrichment": {
"summary": "Diwali, the Hindu Festival of Lights, celebrates the triumph of good over evil through five days of lamp lighting, fireworks, and family gatherings...",
"kid_friendly_explanation": "Diwali is like a giant birthday party for light! Families light thousands of little oil lamps...",
"historical_timeline": "Ancient origins in Hindu epics (circa 500 BCE) → Gained prominence during Gupta Empire...",
"travel_advice": "Plan to visit major cities like Jaipur, Varanasi, or Amritsar during Diwali for spectacular celebrations..."
},
"has_ai_data": true,
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-11-20T14:45:00Z"
}
}
Error Response (Festival Not Found):
{
"error": "Not Found",
"message": "Festival with ID 999 does not exist",
"status": 404
}
4. POST /festival
Create a new festival (requires admin API key).
Request Body:
{
"name": "Cherry Blossom Festival",
"alternative_names": ["Hanami", "Sakura Matsuri"],
"country_id": 3,
"date": "2026-04-01",
"type": "cultural",
"description": "A celebration of the blooming of cherry blossoms across Japan, marking the arrival of spring.",
"significance": "Represents the ephemeral nature of life in Japanese culture and philosophy.",
"traditions": [
"Picnicking under cherry trees",
"Traditional music and dance performances",
"Photography of blossoms",
"Special seasonal foods"
]
}
Demo
Example 1: Get Festival by Id
Example 2: Festival and country APIs
Example 3: Members APIs
Example 4: Authentication APIs
The AI Prompt I Used
Here is the complete prompt I used to generate the initial backend with Xano's AI:
Create a production-ready REST API for a global festival and cultural events database called FestiFlow.
CORE REQUIREMENTS:
Database Schema:
1. Countries table: id, name, country_code
2. Festivals table: id, name, alternative_names (array), country_id (foreign key), date, month (extracted from date), type (enum: religious, cultural, national, seasonal), description, significance, traditions (array), has_ai_data (boolean)
3. AI_Enrichment table: id, festival_id (foreign key), summary (3 sentences), kid_friendly_explanation, historical_timeline, travel_advice, generated_at (timestamp)
4. API_Keys table: id, key (unique), role (enum: public, admin), rate_limit_daily, rate_limit_per_second, created_at
API Endpoints:
1. GET /countries - List all countries with pagination
2. GET /festivals - List festivals with filters: country_id, month, name (search), include_ai_data (optional boolean)
3. GET /festivals/{id} - Get single festival with optional AI data
4. POST /festivals - Create new festival (admin only)
5. POST /festivals/{id}/generate-ai-data - Trigger AI enrichment generation
Authentication:
- API key authentication via X-API-Key header
- Public keys: read access only
- Admin keys: full CRUD access
- Return 401 for invalid keys, 403 for insufficient permissions
Rate Limiting:
- 100 requests per day per API key
- 10 requests per second burst limit
- Return 429 with retry_after when exceeded
- Include rate limit headers in all responses
Validation:
- Validate all inputs (required fields, data types, formats)
- Return 400 with descriptive errors for invalid data
- Validate country_id exists when creating festivals
- Validate month is 1-12, date format is YYYY-MM-DD
Pagination:
- Support page and per_page query parameters
- Default per_page: 20, max: 100
- Return pagination metadata: page, per_page, total_items, total_pages
Error Handling:
- Consistent JSON error format: {error, message, status}
- Proper HTTP status codes (200, 201, 400, 401, 403, 404, 429, 500)
- Log errors for debugging
- Never expose internal implementation details
AI Integration:
- When generate-ai-data endpoint called, create AI enrichment record
- Summary should be compelling, 3 sentences, suitable for cards/listings
- Kid-friendly explanation: simple language, engaging, educational
- Historical timeline: brief evolution of the tradition
- Travel advice: practical tips for tourists attending the event
- Mark has_ai_data as true after successful generation
Response Format:
- Wrap single items in {data: {...}}
- Wrap arrays in {data: [...], pagination: {...}}
- Include related data (country object, not just country_id)
- Use consistent date format: ISO 8601
- Use snake_case for all JSON keys
Performance:
- Index foreign keys and frequently queried fields
- Use efficient queries with proper joins
- Cache country list
- Optimize search queries on festival names
Security:
- Sanitize all inputs to prevent SQL injection
- Validate API keys on every request
- Don't expose API key values in responses
- Use secure random generation for API keys
- Implement proper CORS headers
Make the API production-ready, developer-friendly, and suitable for real-world applications.
How I Refined the AI-Generated Backend
While Xano's AI produced an impressive starting point, transforming it into a truly production-ready API required thoughtful refinement. Here's how I elevated the AI-generated code to professional standards:
1. Enhanced Authentication Middleware
Before (AI-Generated):
// Basic API key check
if (!request.headers['x-api-key']) {
return {error: "Missing API key", status: 401};
}
let key = apiKeys.find(k => k.key === request.headers['x-api-key']);
if (!key) {
return {error: "Invalid API key", status: 401};
}
After (My Refinement):
// Robust authentication with detailed logging and error handling
const apiKey = request.headers['x-api-key'];
if (!apiKey || apiKey.trim() === '') {
logger.warn('Authentication attempt without API key', {
ip: request.ip,
endpoint: request.path
});
return {
error: "Authentication Required",
message: "Please include your API key in the X-API-Key header",
status: 401
};
}
// Query with indexing for performance
const key = await db.query(
'SELECT * FROM api_keys WHERE key = ? AND is_active = true',
[apiKey]
);
if (!key || key.length === 0) {
logger.warn('Authentication failed: invalid key', {
key_prefix: apiKey.substring(0, 8) + '...',
ip: request.ip
});
return {
error: "Invalid API Key",
message: "The provided API key is invalid or has been revoked",
status: 401
};
}
// Attach key metadata for downstream use
request.apiKey = key[0];
request.userRole = key[0].role;
Why This Matters:
- Security logging for audit trails
- Detailed error messages help developers debug faster
- Active key checking prevents revoked keys from working
- Performance optimization through indexed queries
- Request context enrichment for role-based authorization
My Experience with Xano
Building FestiFlow AI with Xano was a revelation in modern backend development. Here's my honest experience:
What Worked Exceptionally Well
Speed of Initial Development
The AI backend generation got me from concept to working prototype in under an hour. I provided a detailed prompt, and Xano created:
- A complete database schema with proper relationships
- Functional API endpoints with routing
- Basic authentication and validation
- Initial documentation structure
This eliminated the tedious setup work that usually consumes the first days of a project.
Intelligent Architecture Decisions
What impressed me most wasn't just that the AI generated code—it made sensible architectural choices:
- Normalized database design with foreign keys
- RESTful endpoint naming conventions
- Proper HTTP status code usage
- Logical separation of concerns
These weren't just "working" solutions; they were genuinely good patterns I might have chosen myself.
Documentation is Still Manual
While AI can generate code, creating truly helpful developer documentation requires human empathy. Understanding what developers will struggle with, providing relevant examples, and explaining the "why" behind design decisions—these remain human strengths.
Conclusion
FestiFlow AI represents more than just a technical achievement, it's a step toward democratizing access to cultural knowledge. In a world where understanding and appreciating diverse traditions is more important than ever, tools that make this information accessible to developers can create ripples of positive impact.
Thank you for reading, and happy coding! 🎉
Have questions or feedback? I'd love to hear from you in the comments below!
Top comments (3)
This is an incredibly impressive build! 🔥 The level of detail, from the structured festival data to the AI-generated cultural insights, makes FestiFlow AI so much more than a typical API. I love how you refined the AI-generated backend into a truly production-ready system, especially the authentication and rate-limiting work.
Great job! 👏🏻
I'm glad that you liked it 😁
This is fantastic! Great job and thanks for sharing. 🙌