Slouch API

A RESTful API designed to help developers integrate booking functionality into their products. Slouch provides a complete booking management system with project organization, allowing you to manage bookings across multiple projects.

Overview

Slouch API enables developers to quickly add booking capabilities to their applications. It handles the core booking logic, data persistence, and provides a clean REST interface for managing bookings and projects.

Key Features

• Project Management: Organize bookings under projects
• Project Configuration: Configure timezone, booking limits, and allowed time ranges per project
• Booking Management: Create, read, update, and delete bookings with date and time support
• Timezone Support: Automatic timezone conversion - clients can book in any timezone, API stores in project's timezone
• Booking Validation: Enforce max bookings per day and allowed booking time ranges
• Relationship Management: Bookings are automatically associated with projects
• Cascade Deletion: Deleting a project automatically removes all associated bookings and config
• RESTful API: Clean, intuitive endpoints following REST conventions
• OpenAPI Documentation: Auto-generated API documentation for easy integration

Tech Stack

• .NET 9.0: Modern C# framework
• PostgreSQL: Robust relational database
• Entity Framework Core: ORM for database operations
• AutoMapper: Object-to-object mapping
• Docker: Containerized PostgreSQL database
• OpenAPI/Swagger: API documentation

Architecture

The project follows Clean Architecture principles with clear separation of concerns:

Slouch.API/              # API layer (Controllers, Program.cs)
Slouch.Application/       # Application layer (Services, DTOs, Mappings)
Slouch.Domain/           # Domain layer (Entities, Interfaces)
Slouch.Infrastructure/   # Infrastructure layer (Data Access, Repositories)

Getting Started

Prerequisites

• .NET 9.0 SDK
• Docker and Docker Compose
• Make (optional, for using Makefile commands)

Setup

1. Clone the repository

   git clone <repository-url>
   cd Slouch

2. Start the PostgreSQL database

   docker-compose up -d

   This starts PostgreSQL on port 5433 (to avoid conflicts with local PostgreSQL).

3. Update connection string (if needed)

   The connection string is configured in Slouch.API/appsettings.Development.json:

   {
     "ConnectionStrings": {
       "DefaultConnection": "Host=localhost;Port=5433;Database=slouch_db;Username=slouch_user;Password=slouch_password"
     }
   }

4. Run database migrations

   make migration-apply

   Or manually:

   dotnet ef database update --project Slouch.Infrastructure --startup-project Slouch.API

5. Run the API

   cd Slouch.API
   dotnet run

6. Access the API

   • API Base URL: https://localhost:5001 or http://localhost:5000
   • OpenAPI Documentation: https://localhost:5001/openapi/v1.json (in development)

API Endpoints

Authentication

Manage authentication for the API.

Login

POST /api/auth/github
Content-Type: application/json

{
  "gitHubToken": "{Fine-grained Personal Access Token (FGPAT) from GitHub}",
}

Projects

Manage projects that organize your bookings.

Get All Projects

GET /api/projects

Get Project by ID

GET /api/projects/{id:guid}

Create Project

POST /api/projects
Content-Type: application/json

{
  "name": "My Project",
  "timeZoneId": "America/New_York",
  "maxBookingsPerDay": 10,
  "allowedBookingStartTime": "09:00:00",
  "allowedBookingEndTime": "17:00:00"
}

Note: All config fields are optional. If not provided:

• timeZoneId defaults to "UTC"
• maxBookingsPerDay is null (unlimited bookings)
• allowedBookingStartTime and allowedBookingEndTime are null (no time restrictions)

Minimal example (config will be created with UTC timezone):

{
  "name": "My Project"
}

Update Project

PUT /api/projects/{id:guid}
Content-Type: application/json

{
  "id": "guid-here",
  "uid": "project-uid",
  "name": "Updated Project Name"
}

Delete Project

DELETE /api/projects/{id:guid}

Note: Deleting a project will cascade delete all associated bookings and configuration.

Project Configuration

Configure project-specific settings like timezone, booking limits, and allowed time ranges.

Get Project Configuration

GET /api/projects/{projectId:guid}/config

Create Project Configuration

POST /api/projects/{projectId:guid}/config
Content-Type: application/json

{
  "timeZoneId": "America/New_York",
  "maxBookingsPerDay": 10,
  "allowedBookingStartTime": "09:00:00",
  "allowedBookingEndTime": "17:00:00"
}

Update Project Configuration

PUT /api/projects/{projectId:guid}/config
Content-Type: application/json

{
  "timeZoneId": "America/New_York",
  "maxBookingsPerDay": 15,
  "allowedBookingStartTime": "08:00:00",
  "allowedBookingEndTime": "18:00:00"
}

Delete Project Configuration

DELETE /api/projects/{projectId:guid}/config

Note:

• timeZoneId is required and must be a valid IANA timezone identifier (e.g., "America/New_York", "Europe/London", "Asia/Tokyo")
• maxBookingsPerDay, allowedBookingStartTime, and allowedBookingEndTime are optional
• A project must have a configuration before bookings can be created
• Bookings are validated against these settings (max bookings per day, allowed time range)

Bookings

Manage bookings within projects.

Get All Bookings

GET /api/bookings

Get Booking by ID

GET /api/bookings/{id:guid}

Create Booking

POST /api/bookings
Content-Type: application/json

{
  "projectId": "project-guid-here",
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "date": "2024-01-15T14:30:00+09:00"
}

Note:

• The date field now accepts ISO 8601 datetime with timezone (e.g., "2024-01-15T14:30:00+09:00")
• Clients can send booking times in any timezone. The API automatically converts the time to the project's configured timezone before storing.
• The booking will be validated against the project's configuration:
  • If maxBookingsPerDay is set, the booking will be rejected if the limit is reached for that date
  • If allowedBookingStartTime and allowedBookingEndTime are set, the booking time must fall within this range

Update Booking

PUT /api/bookings/{id:guid}
Content-Type: application/json

{
  "id": "booking-guid-here",
  "projectId": "project-guid-here",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "date": "2024-01-16T10:00:00-05:00"
}

Note:

• Bookings cannot be moved between projects. The projectId in the update request is ignored.
• The booking time will be converted to the project's timezone and validated against the project configuration.

Delete Booking

DELETE /api/bookings/{id:guid}

Data Models

Project

{
  "id": "guid",
  "uid": "unique-project-identifier",
  "name": "Project Name"
}

Project Configuration

{
  "projectId": "project-guid",
  "timeZoneId": "America/New_York",
  "maxBookingsPerDay": 10,
  "allowedBookingStartTime": "09:00:00",
  "allowedBookingEndTime": "17:00:00",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Fields:

• timeZoneId (required): IANA timezone identifier (e.g., "America/New_York", "Europe/London")
• maxBookingsPerDay (optional): Maximum number of bookings allowed per day
• allowedBookingStartTime (optional): Start of allowed booking window (HH:mm:ss format)
• allowedBookingEndTime (optional): End of allowed booking window (HH:mm:ss format)

Booking

{
  "id": "guid",
  "projectId": "project-guid",
  "name": "Customer Name",
  "email": "customer@example.com",
  "phone": "+1234567890",
  "date": "2024-01-15T14:30:00-05:00",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Note: The date field is now a DateTimeOffset (ISO 8601 format with timezone). Booking times are stored in the project's configured timezone, but clients can send times in any timezone - the API handles the conversion automatically.

Database Management

Creating Migrations

make migration-add NAME=YourMigrationName

Applying Migrations

make migration-apply

Other Useful Commands

make db-up          # Start PostgreSQL container
make db-down        # Stop PostgreSQL container
make db-reset       # Start DB and apply migrations
make db-drop        # Drop the database

Development

Project Structure

• Slouch.Domain: Core domain entities and interfaces
• Slouch.Application: Business logic, services, DTOs, and AutoMapper profiles
• Slouch.Infrastructure: Data access layer, repositories, and EF Core configuration
• Slouch.API: REST API controllers and application startup

Key Design Decisions

• GUID Primary Keys: All entities use GUID for primary keys
• Snake Case Database: Tables and columns use snake_case naming convention
• Cascade Delete: Deleting a project automatically deletes all its bookings and configuration
• Immutable Project Assignment: Bookings cannot be moved between projects after creation
• Soft Delete Support: BaseEntity includes DeletedAt for soft delete capability
• Project Configuration: Project-specific settings (timezone, limits, time ranges) are stored in a separate ProjectConfig entity
• Timezone Handling: API automatically converts booking times to the project's timezone, allowing clients worldwide to book without timezone conversion logic
• IANA Timezone Identifiers: Using IANA timezone IDs (e.g., "America/New_York") for better DST handling and cross-platform compatibility

Configuration

Database Connection

Configure the connection string in appsettings.Development.json or appsettings.json:

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5433;Database=slouch_db;Username=slouch_user;Password=slouch_password"
  }
}

Docker Compose

The docker-compose.yml file configures PostgreSQL with:

• Database: slouch_db
• User: slouch_user
• Password: slouch_password
• Port: 5433 (mapped from container port 5432)

Contributing

1. Follow the existing code structure and patterns
2. Ensure all migrations are applied before committing
3. Run linter checks before submitting changes
4. Update documentation for any API changes

License

[Add your license here]

Support

For issues, questions, or contributions, please create an issue or contact the maintainers.