shards.info
crystal-api-starter
💎 crystal-api-starter
A modern JSON API starter for Crystal.
Ruby-like syntax, compiled speed, and a single static binary in a tiny `FROM scratch` Docker image.
What's inside
| 🚀 Kemal | Fast, Sinatra-style routing |
| 🧱 Typed JSON | JSON::Serializable models and request structs, validation with clear errors |
| 🔒 Thread-safe store | In-memory, mutex-guarded, easy to swap for Postgres or SQLite |
| 🧪 Specs | Request specs with spec-kemal |
| 🧹 Linting | Ameba + crystal tool format |
| 🐳 Docker | Static binary in a FROM scratch image |
| 🤖 CI | Format, lint, specs and Docker build on every push |
Quick start
git clone https://github.com/stijnwtf/crystal-api-starter my-api
cd my-api
shards install
crystal run src/app.cr # http://localhost:3000
Needs Crystal 1.21+ (brew install crystal).
$ curl -X POST localhost:3000/tasks -d '{"title":"Try Crystal"}'
{"id":1,"title":"Try Crystal","completed":false,"created_at":"2026-10-09T09:29:56Z"}
Commands
| Command | Does |
|---|---|
make dev |
Run with auto-restart (watchexec) |
make test |
Run specs |
make lint |
Run Ameba |
make format |
Format code |
make build |
Optimized binary in bin/app |
make docker |
Build the production image |
API
| Method | Path | Body | Response |
|---|---|---|---|
GET |
/health |
{"status","version"} |
|
GET |
/tasks |
Task[] |
|
GET |
/tasks/:id |
Task or 404 |
|
POST |
/tasks |
{"title"} |
201 Task, 400 or 422 |
PATCH |
/tasks/:id |
{"title"?, "completed"?} |
Task, 404 or 422 |
DELETE |
/tasks/:id |
204 or 404 |
Structure
src/
├── app.cr entry: config, JSON error handlers, server start
├── store.cr thread-safe in-memory store
├── models/task.cr Task model, request bodies, validation
└── routes/ one file per resource
spec/ request specs
Add a resource: create src/models/thing.cr and src/routes/things.cr. Both folders are required with a glob, so no wiring needed.
Deploy
docker build -t my-api .
docker run -p 3000:3000 my-api
Configure the port with PORT (default 3000).
If this saved you time, a ⭐️ helps others find it.
License
Repository
crystal-api-starter
Owner
Statistic
- 0
- 0
- 0
- 0
- 3
- about 1 hour ago
- October 9, 2026
License
MIT License
Links
Synced at
Fri, 09 Oct 2026 09:33:39 GMT
Languages