CityNext - Visit Booking API

A simple Go REST API for booking visits with holiday validation and duplicate prevention.

Features

• Visit Booking: Book visits with first name, last name, and visit date
• Holiday Validation: Prevents booking on UK public holidays using nager.date API
• Duplicate Prevention: Only one visit allowed per date
• Database: SQLite with migration support
• Testing: Comprehensive unit tests with mocking

API Endpoints

POST /

Book a new visit.

Request Body:

{
  "first_name": "Carlos",
  "last_name": "Vieira",
  "visit_date": "2025-12-25"
}

Response (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "Carlos",
  "last_name": "Vieira",
  "visit_date": "2025-12-25",
  "created_at": "2025-09-23T13:00:00Z",
  "updated_at": "2025-09-23T13:00:00Z"
}

Error Responses:

• 400 - Invalid request body
• 500 - Internal server error

Architecture

Project Structure

.
├── cmd/
│   └── main.go                 # Application entry point
├── configs/                    # Configuration management
├── migrations/                 # Database migration
├── models/                     # Data models
├── repository/                 # Database operations
├── server/                     # HTTP server and endpoint
├── services/
│   ├── holiday_service.go      # Holiday API integration

Design Decisions

1. Simple Architecture

• Basic handler-based approach for better maintainability
• Repository pattern for database abstraction
• Service pattern for business logic separation

2. SQLite with go-migrate

• Used go-migrate for database migrations

3. Date-Only Format

• API accepts and returns dates in YYYY-MM-DD format
• Custom DateOnly type for proper JSON marshaling/unmarshaling
• Time component ignored for business logic

4. Holiday Service Integration

• Nager.date API for UK public holidays
• Custom HolidayDate type to handle API's date format
• Proper error handling with meaningful error messages
• Interface-based design for easy mocking

5. Validation Approach

• Echo validator with go-playground/validator/v10
• Business logic validation separate from input validation
• Past date validation using date-only comparison

Configuration

Configure via environment variables:

export APP_PORT=8080
export APP_DB_PATH=./data/citynext.db
export APP_NAGER_URL=https://date.nager.at/api/v3

Running the Application

Prerequisites

• Go 1.24+
• SQLite3

Development

# Run the application
go run cmd/main.go

# Run tests
make test

# Build
go build ./...

Testing

The project includes comprehensive testing:

• Unit Tests: Repository, services, and utilities
• Integration Tests: HTTP handlers with mocking on ./server/book_test.go
• Test Coverage: All critical paths covered

Testing tools used:

• testify for assertions and mocking
• apitest for HTTP handler testing
• In-memory SQLite for repository tests

Key Components

Models

• Visit: Core entity with UUID, names, date, and timestamps
• DateOnly: Custom type for date-only JSON handling

Repository

• VisitRepository: Database operations with error handling

Services

• HolidayService: Integration with nager.date API
• HolidayDate: Custom unmarshaling for API date format

Server

• Echo Framework: HTTP routing and middleware
• Custom Validator: Input validation with go-playground/validator
• Error Handler: Consistent error responses

Future Improvements

1. Holiday Service Caching

Benefits:

• Reduce API calls to Nager.Date
• Improve response times
• Handle API rate limits gracefully

2. Reliability Features

• Retry Logic: Exponential backoff for external API calls