Beyor-Dato Portfolio 179 - Crystal REST API

A compiled, performant REST API built with Crystal, leveraging Crystal's Ruby-like syntax, strong type inference, and the Kemal web framework to create fast, expressive systems with compile-time correctness and zero-cost abstractions.

Architecture Highlights

Technology Stack

Language: Crystal 1.11+ (compiled, Ruby-like syntax)
Runtime: Native binary (LLVM-compiled)
Framework: Kemal (lightweight web framework)
Type System: Strong static typing with type inference
Build Tool: Shards (Crystal package manager)
Paradigm: Object-oriented with functional elements
Concurrency: Fibers (lightweight green threads)

Key Features

Compiled Language: Native binaries without runtime
Ruby Syntax: Familiar syntax with static type safety
Type Inference: Strong types inferred from context
Fast Performance: LLVM optimization, C-speed execution
Fibers: Lightweight concurrency for I/O-bound tasks
Macros: Compile-time code generation
Zero-Cost Abstractions: No runtime overhead
Memory Safety: No null pointers or segfaults (safe subset)
Static Dispatch: Compile-time method resolution
Interoperability: Call C libraries directly

Project Structure

beyor-dato-portfolio-179/
├── shard.yml            # Crystal package manifest
├── src/
│   ├── main.cr          # Kemal REST API application
│   └── models.cr        # Data models and factories
├── Dockerfile           # Container build
├── docker-compose.yml   # Development stack
├── .gitignore           # Git exclusions
└── 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, compiled languages, and high-performance systems",
  "portfolio_url": "https://beyor-dato.dev"
}

List Projects

GET /api/projects
Response: {
  "projects": [
    {
      "id": "UUID",
      "title": "Dynamic REST API",
      "description": "High-performance REST API built with Crystal's compiled speed and Kemal web framework",
      "technologies": ["Crystal", "Kemal", "Compiled", "REST"],
      "repository": "https://github.com/Beyor-Dato/beyor-dato-portfolio-179"
    }
  ]
}

Development Setup

Prerequisites

Crystal 1.11+ (https://crystal-lang.org/install/)
LLVM 11+ (installed with Crystal)
Docker (for containerized development)

Installation

macOS

# Install Crystal using Homebrew
brew install crystal

# Verify installation
crystal --version

Linux

# Ubuntu/Debian
curl -fsSL https://crystal-lang.org/install.sh | sudo bash

# Arch Linux
sudo pacman -S crystal

# Verify
crystal --version

Windows

# Install via MSIX or WSL2
# Download from https://crystal-lang.org/install/

# Verify
crystal --version

Local Development

# Install dependencies
shards install

# Run the server
crystal run src/main.cr

# Test the API
curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/api/developer
curl http://127.0.0.1:8000/api/projects

# Build optimized binary
crystal build -O3 src/main.cr -o app

# Run compiled binary
./app

# Run tests
crystal spec

# Format code
crystal tool format

# Check for issues
crystal tool implementation

Production Deployment with Docker

# Build and start the service
docker-compose up -d

# View logs
docker-compose logs -f app

# Check health
curl http://localhost:8000/health

# Stop services
docker-compose down

# Build image
docker build -t beyor-dato-portfolio-179 .

# Run container
docker run -p 8000:8000 beyor-dato-portfolio-179

Performance Characteristics

Startup Time: <100ms (native binary)
Memory Usage: ~10-20MB base (minimal overhead)
Throughput: 100,000-500,000+ requests/second
Container Size: ~10-15MB (Alpine static binary)
Response Time: <1ms per operation
Compilation: Fast native compilation
Concurrency: Fibers (100k+ concurrent tasks)
Safety: Memory-safe, no null pointers
Latency: Predictable, low latency
Binary Size: Small static executables

Crystal Language Features

Type Inference: Strong types inferred from context
Structs and Classes: Object-oriented with value types
Union Types: Type-safe sum types (String | Int)
Macros: Compile-time code generation
Fibers: Lightweight green threads for I/O
Pattern Matching: Destructuring with case/when
String Interpolation: Embedded expressions
Blocks and Procs: First-class callable objects
Modules: Namespacing and mixins
C Interop: Direct C library bindings

Crystal Syntax Highlights

Variables and Types

# Variable with type inference
name = "Beyor-Dato"
age = 30

# Explicit type annotation
port : Int32 = 8000
host : String = "127.0.0.1"

# Union types (sum types)
value : String | Int32 = "hello"

# Type checking with is_a?
if value.is_a?(String)
  puts value.upcase
end

Methods and Functions

# Method definition
def greet(name : String) : String
  "Hello, #{name}!"
end

# Method with default parameters
def add(a : Int32, b : Int32 = 0) : Int32
  a + b
end

# Block parameter
def each_item(items : Array(String))
  items.each do |item|
    yield item
  end
end

# Call with block
each_item(["a", "b"]) do |item|
  puts item
end

Structs and Classes

# Struct (value type)
struct Developer
  property id : String
  property name : String
  property email : String

  def initialize(@id, @name, @email)
  end
end

# Class (reference type)
class Project
  property id : String
  property title : String

  def initialize(@id, @title)
  end
end

# Create instances
dev = Developer.new("123", "Alice", "alice@example.com")
project = Project.new("456", "API")

Pattern Matching and Case

# Case expression with pattern matching
case value
when 0
  puts "Zero"
when 1..10
  puts "Between 1 and 10"
when String
  puts "String: #{value}"
else
  puts "Unknown"
end

# Destructuring
point = {1, 2}
case point
when {0, 0}
  puts "Origin"
when {x, y}
  puts "Point: #{x}, #{y}"
end

Array and Enumerable Operations

# Array literal
numbers = [1, 2, 3, 4, 5]

# Array methods
doubled = numbers.map { |x| x * 2 }
evens = numbers.select { |x| x % 2 == 0 }
sum = numbers.sum

# Ranges
(1..10).each { |i| puts i }

# Each with index
numbers.each_with_index do |num, idx|
  puts "#{idx}: #{num}"
end

JSON Serialization

require "json"

# Include JSON::Serializable
struct Person
  include JSON::Serializable

  property name : String
  property age : Int32
end

# Automatic JSON conversion
person = Person.new("Alice", 30)
json = person.to_json
parsed = Person.from_json(json)

Kemal Web Framework

require "kemal"

# GET route
get "/health" do
  {status: "healthy"}.to_json
end

# POST route
post "/api/projects" do |env|
  name = env.params.json["name"].as(String)
  {id: UUID.random.to_s, name: name}.to_json
end

# Middleware
before_all do |env|
  env.response.content_type = "application/json"
end

# Error handling
error 404 do |env|
  {error: "Not Found"}.to_json
end

# Start server
Kemal.run(host: "127.0.0.1", port: 8000)

Crystal Philosophy

Crystal emphasizes:

Expressiveness: Ruby-like syntax with static typing
Performance: Compiled to native code for speed
Simplicity: Minimal boilerplate with type inference
Safety: Memory-safe without garbage collection overhead
Productivity: Fast feedback with rapid compilation
Pragmatism: Familiar syntax for Ruby developers
Efficiency: Small binaries with zero-cost abstractions
Concurrency: Fibers for I/O-bound parallelism
Reliability: Strong types prevent whole categories of bugs
Community: Growing ecosystem with quality libraries

Crystal is designed for developers building fast, compiled systems with Ruby-like expressiveness.

Why Crystal for Programming?

Performance: Compiled speed without complexity
Ruby Syntax: Familiar Ruby syntax with static safety
Type Safety: Compile-time type checking
Small Binaries: Native executables without runtime
Fast Compilation: Rapid development feedback
Low Memory: Minimal memory footprint
Concurrency: Fibers for efficient I/O handling
C Interop: Call C libraries directly
Zero-Cost: No overhead for abstractions
Learning Curve: Easy for Ruby developers

Use Cases for Crystal

Web Services: REST APIs with Kemal or Lucky
CLI Tools: Fast, standalone executables
System Tools: Performance-critical utilities
Data Processing: Fast ETL and pipeline tools
Microservices: Lightweight services with fast startup
Backend Services: High-performance backends
Network Tools: Low-latency network services
DevOps: Infrastructure automation tools
Real-Time Systems: Responsive applications
Game Servers: High-performance game backends

Advanced Features

Macros for Code Generation

# Define a macro
macro debug(expr)
  puts "#{{{expr.stringify}}} = #{{{expr}}}"
end

# Use the macro
debug(1 + 2)  # Outputs: 1 + 2 = 3

# Class macro
macro define_getters(*names)
  {% for name in names %}
    def {{name}}
      @{{name}}
    end
  {% end %}
end

Fibers for Concurrency

# Spawn fibers for concurrent I/O
spawn do
  data = fetch_data("url1")
  process(data)
end

spawn do
  data = fetch_data("url2")
  process(data)
end

# Channel for communication
channel = Channel(String).new

spawn do
  channel.send("message")
end

message = channel.receive

C Interoperability

# Link C library
@[Link("curl")]
lib LibCurl
  fun easy_init : Void*
  fun easy_setopt(handle : Void*, option : Int32, ...) : Int32
end

# Use C library
handle = LibCurl.easy_init