# Holiday API Maintenance Guide

**Last Updated:** 2026-01-07

## Annual Maintenance Checklist

### 1. Update Fallback Data

**File:** `v2/data/holidays-fallback.json`

**Steps:**

1. Fetch holidays for new year from OpenHolidays API
2. Update JSON file with new year data
3. Verify all regions are included
4. Test fallback functionality

**Example:**

```bash
# Test API for new year
curl "https://openholidaysapi.org/PublicHolidays?countryIsoCode=DE&validFrom=2027-01-01&validTo=2027-12-31&subdivisionCode=DE-BE"
```

### 2. Verify API Functionality

**Steps:**

1. Test API endpoint for new year
2. Verify all regions return data
3. Check response format hasn't changed
4. Test error handling

### 3. Update Documentation

**Files:**

- `docs/guides/tools-pages/HOLIDAY_API_INTEGRATION.md`
- `docs/guides/tools-pages/HOLIDAY_API_MAINTENANCE.md`
- Tool-specific documentation files

**Updates:**

- Year references
- Example dates
- Test cases

### 4. Test All Tools

**Tools to Test:**

- Arbeitstage-Rechner
- Arbeitszeitrechner
- Any other tools using holiday data

**Test Cases:**

- Different years (current, past, future)
- Different regions (all Bundesländer)
- API failure scenarios
- Offline mode (fallback)

## Monthly Monitoring

### API Health Check

**Check:**

- API availability
- Response times
- Error rates
- Cache hit rates

**Tools:**

- Browser DevTools Network tab
- Server logs
- Error tracking

### Data Accuracy

**Verify:**

- Holidays match official sources
- Regional variations correct
- No missing holidays
- No incorrect holidays

## Quarterly Review

### Performance Analysis

**Metrics:**

- Average API response time
- Cache hit percentage
- Fallback usage frequency
- User-reported issues

### Code Review

**Check:**

- Service code for improvements
- Error handling robustness
- Caching efficiency
- Code documentation

## Emergency Procedures

### API Downtime

**If OpenHolidays API is down:**

1. Service automatically falls back to local data
2. Monitor API status
3. Update fallback data if needed
4. Notify team if extended downtime

### Data Inconsistencies

**If holidays are incorrect:**

1. Verify against official sources
2. Check region code mapping
3. Update fallback data
4. Clear cache: `holidayService.clearCache()`

### Rate Limit Issues

**If API rate limits hit:**

1. Increase cache duration temporarily
2. Optimize API calls
3. Consider alternative API
4. Enhance fallback data

## Update Process

### Adding New Region

1. Add region code mapping to `holiday-service.js`
2. Add fallback data to `holidays-fallback.json`
3. Test API returns data for region
4. Update documentation

### Adding New Country

1. Add country code to `getCountryCode()`
2. Add subdivision codes to `getSubdivisionCode()`
3. Add fallback data structure
4. Test API integration
5. Update documentation

## Testing Checklist

### Unit Tests

- [ ] API fetching works
- [ ] Caching works correctly
- [ ] Fallback mechanism works
- [ ] Region code conversion correct
- [ ] Date filtering works

### Integration Tests

- [ ] Real API calls succeed
- [ ] API failure triggers fallback
- [ ] Offline mode works
- [ ] Cross-tool consistency

### Browser Tests

- [ ] Chrome
- [ ] Firefox
- [ ] Safari
- [ ] Edge
- [ ] Mobile browsers

## Contact & Support

**For Issues:**

- Check documentation first
- Review error logs
- Test with browser DevTools
- Contact development team

**API Provider:**

- OpenHolidays API: https://openholidaysapi.org
- Documentation: Check API website
- Support: Check API provider support channels