🎉 Holiday API Indonesia 🇮🇩

<img src="https://img.shields.io/badge/Go-1.23+-00ADD8?style=for-the-badge&logo=go&logoColor=white" alt="Go Version"> <img src="https://img.shields.io/badge/Docker-Ready-2496ED?style=for-the-badge&logo=docker&logoColor=white" alt="Docker"> <img src="https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge" alt="License"> <img src="https://img.shields.io/badge/Swagger-API%20Docs-orange?style=for-the-badge&logo=swagger&logoColor=white" alt="Swagger"> <img src="https://img.shields.io/badge/REST-API-blue?style=for-the-badge" alt="REST API"> Production-ready REST API for Indonesian National Holidays & Joint Leave Days Based on official SKB 3 Menteri regulations | JWT Authentication | Rate Limiting | Audit Logging <a href="#-quick-start">Quick Start</a> • <a href="#-api-documentation">API Docs</a> • <a href="#-use-cases">Use Cases</a> • <a href="#-sdk--clients">SDK</a> • <a href="#-self-hosting">Self-Hosting</a>

🚀 Live Demo

Public API Endpoint: https://api.holidayapi.id/v1 (Coming Soon - Currently Self-Host)

# Try it now with curl
curl -X GET "https://api.holidayapi.id/v1/holidays/year/2024" \
  -H "Accept: application/json"

✨ Features

🔐 Authentication & Security

✅ JWT Authentication with access & refresh tokens
✅ Role-Based Access Control (RBAC) - Super Admin & Admin roles
✅ User Management - Registration, login, profile management
✅ Password Security - Bcrypt hashing with password policy
✅ Comprehensive Audit Logging - Track all user actions
✅ Security Headers - XSS, CSRF, Content Security Policy protection
✅ Input Sanitization - Protection from injection attacks
✅ Enhanced Rate Limiting - Per-user rate limiting (60 RPM public, authenticated users higher)

🚀 API Features

✅ REST API with versioning (v1)
✅ CRUD operations for admin (JWT protected)
✅ Filter by type - National holidays, joint leave days, or both
✅ Filter by period - Year, month, or specific day queries
✅ Swagger documentation with interactive testing
✅ SQLite database (pure Go, no CGO required)
✅ Comprehensive logging with structured format
✅ Input validation with custom validators
✅ Docker support with production-ready configuration
✅ Unit & Integration tests with mocking

🚀 Quick Start

Prerequisites

Go 1.23 or higher
Git
Docker (optional)

Installation & Running

Option 1: Using Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/ilramdhan/holidayapi.git
cd holidayapi

# Start with Docker Compose
docker-compose up --build

# API is now running at http://localhost:8080

Option 2: Using Go

# Clone the repository
git clone https://github.com/ilramdhan/holidayapi.git
cd holidayapi

# Install dependencies
go mod tidy

# Run the application
go run cmd/server/main.go

Option 3: Install as Go Package

go get github.com/ilramdhan/holidayapi

Verify Installation

# Health check
curl http://localhost:8080/health

# Get API documentation
curl http://localhost:8080/swagger/index.html

📚 API Documentation

Interactive Documentation

Swagger UI: http://localhost:8080/swagger/index.html
OpenAPI Spec: http://localhost:8080/swagger/doc.json

Base URL

http://localhost:8080/api/v1

🔓 Public Endpoints (No Authentication Required)

| Endpoint | Description | Example | |----------|-------------|---------| | GET /api/v1/holidays | Get all holidays with filters | Try it | | GET /api/v1/holidays/year/{year} | Get holidays by year | /holidays/year/2024 | | GET /api/v1/holidays/month/{year}/{month} | Get holidays by month | /holidays/month/2024/1 | | GET /api/v1/holidays/today | Get today's holiday | /holidays/today | | GET /api/v1/holidays/this-year | Get current year holidays | /holidays/this-year | | GET /api/v1/holidays/upcoming | Get upcoming holidays | /holidays/upcoming | | GET /health | Health check | /health |

🔐 Authentication Endpoints

| Endpoint | Description | Auth Required | |----------|-------------|---------------| | POST /api/v1/auth/login | User login (get JWT tokens) | No | | POST /api/v1/auth/refresh | Refresh access token | Refresh Token | | GET /api/v1/auth/profile | Get user profile | JWT | | POST /api/v1/auth/change-password | Change password | JWT |

👑 Admin Endpoints (JWT Required)

| Endpoint | Description | Role | |----------|-------------|------| | POST /api/v1/admin/holidays | Create new holiday | Admin/Super Admin | | PUT /api/v1/admin/holidays/{id} | Update holiday | Admin/Super Admin | | DELETE /api/v1/admin/holidays/{id} | Delete holiday | Admin/Super Admin | | GET /api/v1/admin/audit-logs | View all audit logs | Super Admin |

💡 Use Cases

1. HR & Payroll Systems

Automatically calculate working days, leave balances, and payroll based on official Indonesian holidays.

# Example: Calculate working days in a month
import requests

response = requests.get("https://api.holidayapi.id/v1/holidays/month/2024/1")
holidays = response.json()["data"]

working_days = total_days - len(holidays)

2. Calendar & Scheduling Apps

Display Indonesian holidays in calendar applications and scheduling tools.

3. E-commerce & Retail

Plan promotions and sales around holiday periods. Identify peak shopping seasons.

4. Logistics & Delivery

Optimize delivery schedules by accounting for non-working days and joint leave periods.

5. Banking & Financial Services

Calculate settlement dates, interest calculations, and business days excluding holidays.

6. Government & Public Services

Integrate official holiday data into public service portals and citizen applications.

7. Education & Academic Systems

Schedule exams, breaks, and academic calendars aligned with national holidays.

🎯 Who is This For?

| Audience | Use Case | |----------|----------| | Developers | Build apps with accurate Indonesian holiday data | | HR Teams | Automate leave and payroll calculations | | Startups | Free, reliable holiday API for their products | | Enterprise | Self-hosted solution with full data control | | Government | Public service integration | | Students | Learn Go, REST API, JWT authentication |

🖥️ Self-Hosting Guide

Requirements

Docker & Docker Compose, OR
Go 1.23+ with SQLite support

Docker Deployment

Production Deployment

# Clone repository
git clone https://github.com/ilramdhan/holidayapi.git
cd holidayapi

# Create environment file
cp .env.example .env

# Edit .env with your settings
nano .env

# Start production stack
docker-compose -f docker-compose.yml up -d

Environment Variables

# Server Configuration
SERVER_HOST=0.0.0.0
SERVER_PORT=8080

# Database
DATABASE_PATH=./data/holidays.db
MIGRATIONS_PATH=./migrations

# Security
JWT_SECRET_KEY=your-super-secret-key-min-32-chars
ADMIN_API_KEY=your-admin-api-key

# Rate Limiting
RATE_LIMIT_RPM=60
RATE_LIMIT_BURST=10

# JWT Settings
JWT_ACCESS_TOKEN_TTL=15m
JWT_REFRESH_TOKEN_TTL=168h

Cloud Deployment

Railway

Note: Railway telah menghentikan dukungan untuk template deployment gratis. Silakan gunakan opsi lain di bawah ini atau deploy secara manual.

Render

Fly.io

# Install flyctl
curl -L https://fly.io/install.sh | sh

# Launch app
fly launch

# Deploy
fly deploy

🔧 SDK & Clients

Go SDK

package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/ilramdhan/holidayapi/pkg/client"
)

func main() {
    // Create client
    c := client.New("https://api.holidayapi.id/v1")
    
    // Get holidays for 2024
    holidays, err := c.GetHolidaysByYear(context.Background(), 2024)
    if err != nil {
        log.Fatal(err)
    }
    
    for _, h := range holidays {
        fmt.Printf("%s: %s\n", h.Date, h.Name)
    }
}

JavaScript/TypeScript Client

import { HolidayClient } from '@holidayapi/indonesia';

const client = new HolidayClient('https://api.holidayapi.id/v1');

// Get holidays
const holidays = await client.getHolidaysByYear(2024);
console.log(holidays);

Python Client

from holidayapi import HolidayClient

client = HolidayClient('https://api.holidayapi.id/v1')

# Get holidays for 2024
holidays = client.get_holidays_by_year(2024)
for holiday in holidays:
    print(f"{holiday['date']}: {holiday['name']}")

Postman Collection

📥 Download Postman Collection

🔗 Integrations

n8n Integration

Use our n8n node to automate holiday-aware workflows.

Zapier Integration

Coming soon - Connect Holiday API with 5000+ apps.

Google Calendar

Sync Indonesian holidays to your Google Calendar.

Slack Bot

Get holiday notifications in your Slack workspace.

📖 Usage Examples

Get Holidays by Year

curl -X GE

HolidayApi

Install / Use

README