Beyor-Dato Portfolio 149 - Crystal REST API

A compiled REST API built with Crystal, combining Ruby's expressiveness and elegance with static typing inference, compiled performance, and concurrent capabilities to create fast, maintainable systems without sacrificing developer productivity.

Architecture Highlights

Technology Stack

Language: Crystal 1.12+
Runtime: Compiled to machine code via LLVM
Build System: Crystal compiler with Shards package manager
Standard Library: Crystal stdlib with HTTP server
Paradigm: Object-oriented with functional features

Key Features

Ruby-Like Syntax: Familiar, expressive, beautiful code
Static Typing: Full static typing with type inference
Compiled Performance: Native machine code execution
Concurrent: Green threads (fibers) for concurrent I/O
Type Inference: Powerful type system with minimal annotations
Pattern Matching: Exhaustive matching on types
Macros: Compile-time code generation
Null Safety: Explicit nil handling with union types
Zero Runtime Overhead: No GC pauses, predictable performance
C Interoperability: Direct FFI to C libraries

Project Structure

beyor-dato-portfolio-149/
├── src/
│   └── main.cr                # REST API server
├── shard.yml                   # Project manifest
├── Dockerfile                  # Multi-stage 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 compiled languages and Crystal",
  "portfolio_url": "https://beyor-dato.dev"
}

List Projects

GET /api/projects
Response: {
  "projects": [
    {
      "id": "UUID",
      "title": "Compiled REST API",
      "description": "High-performance REST API built with Crystal",
      "technologies": ["Crystal", "HTTP", "JSON"],
      "repository": "https://github.com/Beyor-Dato/beyor-dato-portfolio-149"
    }
  ]
}

Development Setup

Prerequisites

Crystal 1.12+ (https://crystal-lang.org/install/)
Shards package manager (included with Crystal)
Docker (for containerized development)

Installation

macOS/Linux

# Install Crystal
# macOS: brew install crystal
# Ubuntu: https://crystal-lang.org/install/on_ubuntu/

# Verify
crystal --version
shards --version

Windows

# Use Windows Subsystem for Linux (WSL) recommended
# Or Docker for Windows

# Verify (in WSL)
crystal --version
shards --version

Local Development

# Install dependencies
shards install

# Build the server
crystal build src/main.cr -o app

# Run the server
./app

# 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 release
crystal build src/main.cr -o app --release

# Run tests (if test file exists)
crystal spec

# Code formatting
crystal tool format

# Type checking
crystal check

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

Performance Characteristics

Startup Time: <100ms (compiled native binary)
Memory Usage: ~10-30MB base (minimal overhead)
Throughput: 50,000-500,000+ requests/second
Container Size: ~15-30MB (Alpine + Crystal binary)
Response Time: <1ms per operation
Compilation: Fast (seconds for whole project)
Binary Size: 5-20MB typical executable
Runtime: No garbage collection pauses

Crystal Language Features

Variables: Immutable by default, var for mutation
Types: Static with powerful inference
Classes: Object-oriented with inheritance
Modules: Mixins for code organization
Methods: Instance and class methods
Blocks: Closures and higher-order functions
Ranges: Inclusive and exclusive ranges
Arrays: Dynamic arrays with generics
Hashes: Key-value data structures
Strings: UTF-8 strings with interpolation

Crystal Syntax Highlights

Variables and Types

# Immutable bindings with type inference
name = "Beyor-Dato"
age = 30
value = 3.14

# Explicit type annotations
greeting: String = "Hello"
count: Int32 = 42

# Mutable variables
var counter = 0
counter += 1

# Type unions
result: String | Int32 = "success"
result = 42

# Nil handling
optional_value: String? = nil
optional_value = "has value"

Classes and Methods

class Developer
  getter id : String
  getter name : String
  property email : String

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

  def display : String
    "#{name} (#{email})"
  end

  def self.create(name : String) : Developer
    new(UUID.random.to_s, name, "")
  end
end

dev = Developer.new("123", "Alice", "alice@example.com")
puts dev.display

Functions and Control Flow

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

# Multiple return values
def divide(a : Int32, b : Int32) : Tuple(Int32, String)
  if b == 0
    {0, "division by zero"}
  else
    {a // b, ""}
  end
end

# Pattern matching
case status
when "active"
  puts "Running"
when "paused"
  puts "Paused"
when "stopped"
  puts "Stopped"
else
  puts "Unknown"
end

# Higher-order functions
def apply_twice(f : Int32 -> Int32, x : Int32) : Int32
  f(f(x))
end

square = ->(x : Int32) { x * x }
result = apply_twice(square, 5)  # 625

Collections and Iteration

# Arrays
numbers = [1, 2, 3, 4, 5]

# Iteration
numbers.each do |num|
  puts num
end

# Map transformation
doubled = numbers.map { |x| x * 2 }

# Filter
filtered = numbers.select { |x| x > 2 }

# Fold/reduce
sum = numbers.reduce(0) { |acc, x| acc + x }

# Hashes
person = {"name" => "Alice", "age" => 30}
person["email"] = "alice@example.com"

Macros and Metaprogramming

# Define macro
macro say_hello(name)
  puts "Hello, #{name}!"
end

say_hello("World")  # Generates: puts "Hello, World!"

# Macro for code generation
macro define_getter(name)
  def {{name}}
    @{{name}}
  end
end

class Config
  @database_url : String

  define_getter(database_url)
end

JSON Serialization

class User
  include JSON::Serializable

  property id : String
  property name : String
  property email : String
end

user = User.new("123", "Alice", "alice@example.com")
json = user.to_json
parsed = User.from_json(json)

Concurrency with Fibers

# Green threads (fibers) for concurrent I/O
spawn do
  sleep 1
  puts "Task 1"
end

spawn do
  sleep 2
  puts "Task 2"
end

# Main task continues
puts "Main task"

# Wait for all fibers to complete
Fiber.yield

Crystal Philosophy

Crystal emphasizes:

Simplicity: Ruby-like syntax that developers love
Performance: Compiled code matches C performance
Type Safety: Static typing without verbosity
Expressiveness: Beautiful, readable code
Productivity: Fast development cycles
Concurrency: Green threads for I/O-bound workloads
Correctness: Type checking catches errors early
Interoperability: Direct C FFI support

Crystal is designed for developers who want Ruby's productivity with compiled-language performance and type safety.

Why Crystal for Programming?

Ruby Familiarity: If you know Ruby, you know Crystal
Performance: Compiles to native code, matches C/C++
Type Safety: Static typing catches errors early
Fast Development: Rapid iteration with compiled speed
Concurrency: Easy parallel I/O with fibers
Zero Runtime: No GC pauses, predictable performance
Beautiful Code: Expressive syntax, readable programs
Maintainability: Types + tests = confidence
Interoperability: Call C libraries directly
Small Binaries: Typical executable 5-20MB

Use Cases for Crystal

Web Services: REST APIs, microservices
CLI Tools: Command-line utilities
Data Processing: ETL pipelines, data transformation
System Utilities: System administration tools
Concurrent I/O: High-throughput, I/O-bound services
Network Tools: Proxies, load balancers, routers
DevOps: Infrastructure tooling
Real-Time Systems: Low-latency applications
Game Development: Game servers and tools
Financial Systems: Trading systems, fintech applications

Advanced Features

Generics and Type Parameters

class Box(T)
  def initialize(@value : T)
  end

  def value : T
    @value
  end

  def value=(val : T)
    @value = val
  end
end

int_box = Box(Int32).new(42)
str_box = Box(String).new("hello")

Union Types and Nil Handling

def process(value : String | Int32 | Nil) : String
  case value
  when String
    "Got string: #{value}"
  when Int32
    "Got int: #{value}"
  when Nil
    "Got nil"
  end
end

Method Overloading

def process(value : String) : String
  "String: #{value}"
end

def process(value : Int32) : String
  "Int: #{value}"
end

def process(value : Float64) : String
  "Float: #{value}"
end