Beyor-Dato Portfolio 051 - Crystal Kemal REST API

A blazingly fast REST API built with Crystal and Kemal, showcasing modern compiled language web development with Ruby-like syntax, compile-time type safety, and PostgreSQL integration.

Architecture Highlights

Technology Stack

• Language: Crystal 1.9+ (compiled with LLVM)
• Framework: Kemal 1.3+ (lightweight web framework)
• Database: PostgreSQL 15 with crystal-pg driver
• Dependency Manager: Shards (Crystal package manager)
• Containerization: Docker & Docker Compose

Key Features

1. Compile-Time Type Safety: Crystal's static typing with type inference
2. Ruby-Like Syntax: Clean, expressive syntax with modern language features
3. Native Performance: Compiled to machine code via LLVM backend
4. Minimal Overhead: Lightweight Kemal framework with no middleware bloat
5. Direct PostgreSQL Access: crystal-pg for efficient database queries
6. JSON Serialization: Built-in JSON support with automatic encoding/decoding
7. Production Ready: Single binary deployment with Alpine Linux (~30MB)

Project Structure

beyor-dato-portfolio-051/
├── shard.yml                   # Crystal dependencies and metadata
├── src/
│   └── main.cr                # Single-file application entry point
├── Dockerfile                 # Multi-stage Alpine Linux build
├── docker-compose.yml         # Local development stack
└── README.md                  # This file

API Endpoints

Health Check

GET /health
Response: { "status": "healthy" }

Developer Profile

GET /api/developer
Response: {
  "id": "UUID",
  "name": "Beyor-Dato",
  "email": "davit.gamtenadze320@eab.tsu.edu.ge",
  "bio": "Full-stack developer specializing in Crystal and systems programming",
  "portfolioUrl": "https://beyor-dato.dev"
}

List Projects

GET /api/projects
Response: {
  "projects": [
    {
      "id": "UUID",
      "title": "Project Name",
      "description": "...",
      "technologies": ["Crystal", "Kemal", ...],
      "repository": "..."
    }
  ]
}

Create Project

POST /api/projects
Body: {
  "title": "...",
  "description": "...",
  "technologies": [...],
  "repository": "..."
}
Response: { "status": "created" }

Development Setup

Prerequisites

• Crystal 1.9+ (Download)
• Shards (included with Crystal)
• PostgreSQL client libraries (for local DB connection)

Installation (macOS)

brew install crystal

Installation (Ubuntu/Debian)

sudo apt-get install crystal

Local Development

# Install dependencies
shards install

# Run development server (hot reload enabled)
crystal run src/main.cr

# Server runs on http://localhost:3000

Building Release Binary

# Compile optimized binary
crystal build --release -o portfolio-051 src/main.cr

# Run compiled binary
./portfolio-051

Production Deployment with Docker

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f app

# Stop services
docker-compose down

Performance & Scalability

• Compiled Language: Executes at near-C speed with zero interpretation overhead
• LLVM Backend: Aggressive optimizations through LLVM compiler
• Lightweight Framework: Kemal adds minimal overhead (~100 lines of framework code)
• Type Safety: Compile-time checks prevent runtime type errors
• Memory Efficiency: Stack-allocated types, no garbage collection pauses
• Concurrency: Kemal uses fibers for lightweight concurrent request handling

Benchmarking

# Install benchmarking tool
brew install wrk

# Benchmark health endpoint (100 concurrent connections, 30 seconds)
wrk -t4 -c100 -d30s http://localhost:3000/health

# Expected throughput: 15,000+ requests/second on modern hardware

Database Integration

Connection String

postgresql://postgres:password@localhost:5432/portfolio_db

Environment Variables

DATABASE_URL=postgresql://postgres:password@localhost:5432/portfolio_db
KEMAL_ENV=production
KEMAL_HOST=0.0.0.0
KEMAL_PORT=3000

Code Highlights

Struct with JSON Serialization

struct Developer
  include JSON::Serializable
  
  @[JSON::Field(key: "id")]
  getter id : String
  
  @[JSON::Field(key: "name")]
  getter name : String
end

RESTful Routing

get "/api/developer" do |env|
  developer = Developer.new(
    id: "550e8400-e29b-41d4-a716-446655440000",
    name: "Beyor-Dato",
    ...
  )
  developer.to_json
end

Type-Safe JSON Parsing

body = JSON.parse(env.request.body.not_nil!)
puts "Project: #{body["title"]?}"

Build Artifacts

• Executable: portfolio-051 (~5 MB stripped binary)
• Docker Image: ~30 MB with Alpine Linux base
• Shards Lock: Reproducible dependency versions

Crystal Language Features

• Type Inference: Types inferred at compile-time
• Null Safety: Required not_nil! explicitly marks nullable types
• Pattern Matching: Match expressions with exhaustiveness checking
• Macros: Meta-programming support at compile time
• Concurrency: Fiber-based lightweight threading
• C Interop: Direct bindings to C libraries via FFI

Testing

# Run tests
crystal spec

# Run specific test file
crystal spec spec/api_spec.cr

Deployment

Heroku Deployment

heroku create beyor-dato-portfolio-051
git push heroku main

Kubernetes Ready

The Docker image is minimal and production-ready for Kubernetes deployment with health checks built-in.

Repository

beyor-dato-portfolio-051

Author

Beyor-Dato

• Email: davit.gamtenadze320@eab.tsu.edu.ge
• Portfolio: https://beyor-dato.dev

---

Created: June 2026
Crystal Version: 1.9+
Kemal Version: 1.3+
PostgreSQL Version: 15
License: MIT

Why Crystal?

Crystal combines the elegance of Ruby with the performance of compiled languages. This project demonstrates why Crystal is ideal for:

• High-performance microservices
• Real-time APIs with low latency requirements
• Systems that need expressive syntax AND raw speed
• Teams migrating from Ruby who need better performance