Complete Event Management: Create, read, update, delete, and list calendar events
Google Calendar API Integration: Full integration with Google Calendar v3 API
Domain-Wide Delegation: Impersonate users within your Google Workspace domain
API Key Authentication: Secure access via X-API-Key header
Token Caching: Efficient OAuth token management to minimize authentication requests
Docker Support: Ready for containerized deployment

Prerequisites

Rust 1.75+ (for development)
Docker & Docker Compose (for deployment)
A Google Cloud project with Calendar API enabled
A Google service account with domain-wide delegation configured

Quick Start

1. Environment Setup

Copy the example environment file:

cp .env.example .env

Configure your environment variables:

HOST=127.0.0.1
PORT=4000
API_KEY=your-secret-api-key-here
GOOGLE_CALENDAR_ID=your-calendar-id@group.calendar.google.com
GOOGLE_SERVICE_ACCOUNT_KEY=/path/to/service_account_key.json

2. Google Cloud Setup

Create a service account in Google Cloud Console
Enable the Google Calendar API for your project
Download the service account key JSON file
Configure domain-wide delegation in Google Workspace Admin Console with scope:
- https://www.googleapis.com/auth/calendar

3. Running the Service

Development

cargo run

Production (Docker)

docker-compose up -d

The service will be available at http://localhost:4000.

API Documentation

Authentication

All API endpoints (except /api/v1/health) require authentication via the X-API-Key header:

X-API-Key: your-secret-api-key-here

Endpoints

Health Check

GET /api/v1/health

Returns service health status. No authentication required.

Create Event

POST /api/v1/events
Content-Type: application/json

{
  "id": "optional-custom-id",
  "summary": "Meeting with Team",
  "description": "Weekly sync meeting",
  "location": "Conference Room A",
  "start": {
    "dateTime": "2024-06-15T10:00:00Z",
    "timeZone": "UTC"
  },
  "end": {
    "dateTime": "2024-06-15T11:00:00Z",
    "timeZone": "UTC"
  },
  "attendees": [
    {
      "email": "attendee@example.com",
      "displayName": "John Doe"
    }
  ]
}

Get Event

GET /api/v1/events/{event_id}

List Events

GET /api/v1/events?timeMin=2024-06-01T00:00:00Z&timeMax=2024-06-30T23:59:59Z&maxResults=10&q=meeting

Query parameters:

timeMin: Start of time range (RFC3339)
timeMax: End of time range (RFC3339)
maxResults: Maximum number of events to return
q: Search term

Update Event

PUT /api/v1/events/{event_id}
Content-Type: application/json

{
  "summary": "Updated Meeting Title",
  "description": "Updated description"
}

Delete Event

DELETE /api/v1/events/{event_id}

Configuration

Environment Variables

Variable	Description	Default
`HOST`	Server bind address	`127.0.0.1`
`PORT`	Server port	`4000`
`API_KEY`	Secret key for API authentication	Required
`GOOGLE_CALENDAR_ID`	ID of the Google Calendar to manage	Required
`GOOGLE_SERVICE_ACCOUNT_KEY`	Path to service account key file, base64 encoded JSON, or raw JSON	Required

Service Account Key Formats

The GOOGLE_SERVICE_ACCOUNT_KEY can be provided in three formats:

File path: /path/to/service_account_key.json
Base64 encoded: cat service-account.json | base64 -w 0
Raw JSON: {"type": "service_account", ...} (not recommended for production)

CORS Configuration

CORS is configured in src/main.rs. Modify the allowed origins for your deployment:

let cors = Cors::default()
    .allowed_origin("https://your-app.com")
    // ...

Project Structure

├── Cargo.toml
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── src/
    ├── main.rs           # Application entry point
    ├── config.rs         # Configuration management
    ├── handlers/         # HTTP request handlers
    │   ├── events.rs     # Event CRUD operations
    │   └── health.rs     # Health check endpoint
    ├── middleware/       # HTTP middleware
    │   └── auth.rs       # API key authentication
    ├── models/           # Data models
    │   ├── error.rs      # Error handling
    │   └── event.rs      # Event structures
    └── services/         # Business logic
        └── google_calendar.rs  # Google Calendar API client

Error Handling

The service returns standard HTTP status codes:

Status	Description
`200 OK`	Successful operation
`201 Created`	Event created successfully
`204 No Content`	Event deleted successfully
`400 Bad Request`	Invalid request data
`401 Unauthorized`	Invalid or missing API key
`404 Not Found`	Event not found
`502 Bad Gateway`	Google API error
`500 Internal Server Error`	Server error

Error responses include a JSON body:

{
  "error": "Error type",
  "message": "Detailed error message"
}

Development

Building from Source

git clone <repository>
cd calendar-microservice
cargo build --release

Running Tests

cargo test

Logging

Set the RUST_LOG environment variable to control log levels:

RUST_LOG=info cargo run
RUST_LOG=debug cargo run  # More verbose

License

MIT