Project 123: Crystal/Kemal Todo Service API

A compiled REST API built with Kemal, a lightweight web framework for Crystal that combines Ruby's expressiveness with the performance of compiled languages.

Architecture Overview

Kemal Characteristics

• Fast: Compiled to native code for performance
• Ruby-Like: Familiar syntax from Ruby experience
• Type-Safe: Strong static typing with inference
• Lightweight: Minimal overhead and dependencies
• Production-Ready: Used in production systems
• Composable: Middleware and route composition
• JSON First: Built-in JSON serialization
• Modern: Active development and community

Project Structure

project-123-crystal-kemal/
├── shard.yml                        # Crystal dependency management
├── src/
│   └── app.cr                       # Main application and routes
├── .gitignore                       # Git ignore patterns
└── README.md                        # This file

API Endpoints

Health Check

• GET /health - Service health status

User Management

• GET /api/users - List all users
• POST /api/users - Create new user
• GET /api/users/:id - Get user by ID
• PUT /api/users/:id - Update user
• DELETE /api/users/:id - Delete user

Todo Management

• GET /api/todos - List all todos
• POST /api/todos - Create new todo
• GET /api/todos/:id - Get todo by ID
• PUT /api/todos/:id - Update todo
• DELETE /api/todos/:id - Delete todo

Building and Running

Prerequisites

• Crystal 1.0 or later
• Shards (Crystal package manager)

Setup

cd project-123-crystal-kemal
shards install

Build

shards build

Run

./bin/app

Or run directly:

crystal run src/app.cr

Server starts on port 8080.

Example Requests

Get health:

curl http://localhost:8080/health

Create user:

curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{"id":0,"name":"Charlie Brown","email":"charlie@example.com"}'

List todos:

curl http://localhost:8080/api/todos

Update user:

curl -X PUT http://localhost:8080/api/users/1 \
  -H "Content-Type: application/json" \
  -d '{"id":1,"name":"Alice Updated","email":"alice.updated@example.com"}'

Key Kemal Concepts Demonstrated

1. Route Definition: HTTP verb methods (get, post, put, delete)
2. Path Parameters: Dynamic URL segments
3. JSON Serialization: Automatic with JSON::Serializable
4. Type Safety: Strong typing with inference
5. Status Codes: HTTP response status codes
6. Request/Response: Context-based handling
7. Content Types: Header management
8. Error Responses: JSON error messages

Language Features (Crystal 1.0+)

• Classes: Object-oriented programming
• Type Annotations: Strong typing with inference
• JSON Serializable: Built-in JSON mapping
• String Interpolation: Embedded expressions
• Block Syntax: Ruby-like block passing
• Pattern Matching: Destructuring support
• Generics: Parameterized types
• Modules: Code organization and mixins
• Properties: Automatic getter/setter generation
• Compiled: Native code performance

Use Cases

Kemal excels at:

• Building high-performance REST APIs
• Rapid web development with Ruby familiarity
• Microservices in Crystal
• Real-time applications
• Learning Crystal web development
• Building scalable services
• Systems that need Ruby expressiveness with Go/Rust performance
• Web services requiring low latency

Architectural Patterns

Route Definition

Simple, expressive route definitions:

get "/health" do |env|
  health = HealthResponse.new("healthy", "todo-api", "crystal-kemal")
  env.response.content_type = "application/json"
  health.to_json
end

Path Parameters

Dynamic URL segments:

get "/api/users/:id" do |env|
  id = env.params.url["id"].to_i
  user = users.find { |u| u.id == id }
  # Handle request
end

Request Body Handling

Reading and parsing JSON:

post "/api/users" do |env|
  body = env.request.body.not_nil!.gets_to_end
  data = User.from_json(body)
  # Process user
end

Status Codes

Setting HTTP response codes:

env.response.status_code = 201
env.response.status_code = 404
env.response.status_code = 204

JSON Responses

Automatic serialization with JSON::Serializable:

class User
  include JSON::Serializable
  property id : Int32
  property name : String
  property email : String
end

Kemal Unique Features

• Performance: Compiled language speed with Ruby syntax
• Simplicity: Minimal setup and configuration
• Type Safety: Compile-time error checking
• Built-in JSON: JSON::Serializable for mapping
• Middleware: Composable request processing
• WebSocket Support: Real-time features
• Testing: Integrated testing toolkit
• Zero Dependencies: Standalone web framework

Performance Characteristics

• Throughput: Excellent throughput comparable to Go/Rust
• Latency: Very low response latency
• Memory: Efficient memory usage
• Concurrency: Excellent concurrent handling
• Startup: Fast application startup

Crystal Programming Model

Kemal leverages:

• Type Safety: Static typing prevents errors
• Expressiveness: Ruby-like syntax for readability
• Compiled Performance: Native code execution
• Blocks: Ruby-style block passing
• Generics: Reusable parameterized types
• Pattern Matching: Destructuring patterns
• Method Overloading: Type-based dispatch
• Macros: Compile-time metaprogramming

Comparison with Other Web Frameworks

Kemal focuses on:

• Ruby Expressiveness with compiled performance
• Minimalism vs comprehensive frameworks
• Speed comparable to Rust/Go
• Simplicity of development
• Crystal Integration with web features

When to Use Kemal

Best for:

• Building fast REST APIs
• Teams wanting Ruby-like syntax with performance
• High-performance microservices
• Systems requiring low latency
• Learning Crystal
• Rapid API prototyping
• Real-time applications
• Performance-critical services

Dependencies

Key libraries:

• Kemal: Web framework
• Crystal Standard Library: JSON serialization

This project demonstrates Kemal's commitment to combining Ruby's expressiveness with compiled language performance for building fast, elegant REST APIs.