Getting started with REST API Web Services in Rust using Axum, JWT, SQLx, PostgreSQL, and Redis

A sample starter project for building REST API Web service in Rust using axum, JSON Web Tokens (JWT), SQLx, PostgreSQL, and Redis

Covers:

• REST API server based on axum
  • Routing
  • API versioning
  • API Error responses (structured format)
  • Cross-Origin Resource Sharing (CORS)
  • Graceful shutdown
• Authentication & authorization using JSON Web Tokens (JWT)
  • Login, logout, refresh, and revoking operations
  • Role based authorization
  • Generating and validating access and refresh tokens
  • Setting tokens expiry time (based on configuration)
  • Using refresh tokens rotation technique
  • Revoking issued tokens by using Redis (based on configuration)
    • Revoke all tokens issued until the current time
    • Revoke tokens belonging to the user issued until the current time
    • Cleanup of revoked tokens
• Using PostgreSQLdatabase with SQLx
  • Database migrations
  • Async connection pooling
  • Async CRUD operations and transactions
• Using Redis in-memory storage
  • Async Redis operations
• Configuration settings
  • Loading and parsing .env file
  • Using environment variables
• Logs
  • tracing based logs
• Tests
  • End-to-end API tests
  • Database isolation in tests
• Using Docker
  • Running PostgreSQL and Redis services
  • Building the application using the official Rust image
  • Running the full stack: API + PostgreSQL + Redis
• GitHub CI configuration
  • Running cargo deny to check for security vulnerabilities and licenses
  • Running cargo fmt to check for the Rust code format according to style guidelines
  • Running cargo clippy to catch common mistakes and improving the Rust code
  • Running tests
  • Building the application

REST API Endpoints

• List of available API endpoints: docs/API-endpoints.md
• API request samples in the format RFC 2616: tests/endpoints.http

Public Endpoints

• Health: GET /v1/health
• Version: GET /v1/version

Authentication

• Login: POST /v1/auth/login
• Refresh Tokens: POST /v1/auth/refresh
• Logout: POST /v1/auth/logout
• Revoke Tokens Issued to the User: POST /v1/auth/revoke-user
• Revoke All Issued Tokens: POST /v1/auth/revoke-all
• Cleanup Revoked Tokens: POST /v1/auth/cleanup

Users

• List Users: GET /v1/users
• Get User by ID: GET /v1/users/{user_id}
• Add a New User: POST /v1/users
• Update User: PUT /v1/users/{user_id}
• Delete User: DELETE /v1/users/{user_id}

Accounts

• List Accounts: GET /v1/accounts
• Get Account by ID: GET /v1/accounts/{account_id}
• Add a New Account: POST /v1/accounts
• Update Account: PUT /v1/accounts/{account_id}

Transactions

• Transfer Money: POST /v1/transactions/transfer
• Get Transaction by ID: GET /v1/transactions/{transaction_id}

REST API Request Samples

• Using REST Client for Visual Studio Code. Supports RFC 2616 format used in request samples: tests/endpoints.http.

• Using curl:

  Health check

  curl -i http://127.0.0.1:8080/v1/health

  Login

  curl -i http://127.0.0.1:8080/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password_hash":"7c44575b741f02d49c3e988ba7aa95a8fb6d90c0ef63a97236fa54bfcfbd9d51"}'

  List of users

  curl -i http://127.0.0.1:8080/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkNTFlNjE4Ny1jYmFjLTQ0ZmEtOWE5NS04ZjFkZWJkYmFlZWEiLCJqdGkiOiIwN2Y3OWE0OC1kMWFhLTQ1ZjItOWE5NS05Y2M5MGZiY2UyYTciLCJpYXQiOjE3MzYwMTA3MjIsImV4cCI6MTczNjAxNDMyMiwidHlwIjowLCJyb2xlcyI6ImFkbWluIn0.3f2c_5PyPXMhgu0FIX4--SGjnSDW1GLxL0ba6gSImfM"

Running end-to-end API tests

REST API tests: /tests

docker-compose up -d
cargo test

Running the service (debug build)

docker-compose up -d
cargo run

Running the service in test configuration

ENV_TEST=1 cargo run

Running the service at a specific log level

Setting the RUST_LOG - logging level on the launch:

RUST_LOG=info,hyper=debug,axum_web=trace cargo run

Running the Docker based full stack build

docker-compose -f docker-compose.full.yml up -d

Project Stage

Development: this project is under development.