Rust Starter Kit for Web API Development

Finally, after 2 years of learning Rust, and hard work, I can release and share what I have built. This is my very first project that I shared into public, why I want to share is because I want to know about feedback.

I know this project is imperfect but I believe if I share to the public I can receive some feedback, and that feedback can help me to improve my project.

This project is a Boilerplate or starter kit for those of you who want to build Web API using Rust. The architecture itself on how I cook this project I took the ingredient from some of well known project. Like NestJs, Spring Boot, and Laravel.

Why I’m Building This Project?

I built this project purposely for education, especially for me, because I need some feedback from public, only with this feedback I’ll know what I can improve.

I use this starter kit for my hobby project too, because as we know Rust is like raw material that we need to prepare before we cook, with this project you already prepare so you can focus on the product.

Other than that, when I’m learning Rust for web API there is no solid reference that I can follow, or maybe I don’t know. That is other reason why I make this project, because its good for everybody and good for me too.

Project Overview

axum-starter is a production-ready Rust API starter kit built on Axum 0.8, the most popular async web framework in the Rust ecosystem right now. The full stack includes Diesel 2.3 as the ORM, JWT authentication with Argon2 password hashing, file uploads, structured JSON logging, and auto-generated OpenAPI docs all built in.

The goal is simple, clone the repo, run one command, and you have a working API server that is already production-ready.

Project Source https://github.com/thomijasir/axum-starter

Features

• Axum 0.8 — async web framework with full async/await support
• Diesel 2.3 ORM — SQLite for development, PostgreSQL for production, migrations included
• JWT + Argon2 — token-based authentication and secure password hashing
• File Upload — with MIME type validation
• OpenAPI / Swagger — auto-generated docs, available at /spec in development only
• Structured JSON Logging — via Tracing crate
• Snowflake ID Generation — distributed-safe unique IDs
• Layered Architecture — Controller → Service → Repository pattern

Quick Start

Clone the repo and run:

git clone https://github.com/thomijasir/axum-starter
cd axum-starter
./run.sh dev

Server will start at http://localhost:3099. Open http://localhost:3099/spec to see the Swagger UI with all available endpoints.

Package with runner script run.sh

Instead of running cargo commands directly, this project uses run.sh as the task runner. It automatically loads the correct .env file before running the app, so you don’t have to set environment variables manually every time.

# Currently support and tested on MAC Only
./run.sh dev        # development server with .env.local
./run.sh staging    # run with .env.staging config
./run.sh prod       # run with .env.production config
cargo test          # run the full test suite

Environment Files

The project comes with three environment file templates, one for each stage:

• .env.local — for local development
• .env.staging — for staging environment
• .env.production — for production

I don’t use any third-party only for load env files, instead using direct inject before project run. Easy to use you just copy .env.local to .env, fill in your values, and you are good to go.

Available API Endpoints

This API is just sample you can remove if you don’t need this API.

Project Structure

I know this project structure is opinionated, but I use some reference to define on how I define the project structure. I use Barrel Export pattern combine with MVC so this is the result.

# Just snippet folder structure

axum-starter/
├── src/
│   ├── main.rs
│   ├── config.rs
│   ├── server.rs
│   ├── modules/       # auth, user, health, attachment
│   ├── extractors/
│   ├── services/
│   ├── models/
│   ├── schemas/
│   └── utils/
├── migrations/
├── tests/
├── guide/
├── run.sh
├── docker-compose.yml
└── Dockerfile

Full detail can see in the project.

Project Architecture

The architecture follows a strict layered pattern where HTTP handlers call services, services call repositories, and repositories talk to the database. Nothing goes the other way.

• Request → Controller (HTTP layer)
• Service (Business logic) → Repository (Database layer)
• Database (SQLite / PostgreSQL)

For error handling, errors propagate as string codes like NOT_FOUND or EMAIL_ALREADY_EXISTS, then convert to HTTP status codes at the boundary.

For authentication, I use a self-contained Axum extractor instead of middleware, so handlers can declare their auth requirements directly in the function signature.

Documentation

I also prepare the recepies book to guide how to use this starter kit properly. I know you are a pro in Rust development but I just want to help beginners that still struggle.

• Architecture Guide (guide/ARCHITECTURE.md) — System design, layered architecture, request lifecycle, OpenAPI setup
• Coding Conventions (guide/CONVENTIONS.md) — Module structure, naming conventions, error handling patterns
• Development Rules (guide/RULES.md) — Do’s and don’ts, workflow rules, security guidelines

Conclusion

The goal of this project is for me to learn more about Rust especially on web API development, and share what I have experienced when I’m building this project.

We also can collaborate, if you have some idea don’t hesitate to fork and propose changes, I’ll be happy to review and add those feedback into my project.

And if you find this post useful could you help me do a favor to give a stars on github once it has 100 stars ill share to rust awesome, so everyone can know about this Rust starter kit.