rest-api.ir

Introduction

This project is a small web service developed primarily for learning and experimentation, and is still evolving. The goal is to provide a simple executable that can launch a local REST API with minimal setup. Beyond the utility endpoints for time, IP, and countries, the service now streams Iranian market data (currency, crypto, and gold) from tgju.org on a schedule. If you have ideas or suggestions, I'd be happy to receive pull requests.

Features

• Single Binary Execution: Simply run cargo run or execute the output binary to start all Axum routes with default configurations—no additional tools required. The application listens on APP_HOST:APP_PORT and displays the configured domain in the output if set.
• Automatic Configuration Generation: If no .env file exists, the application automatically creates one with default values including network settings and SQLite database configuration, allowing you to run immediately without hassle.
• Ready-to-Use Utility Routes: A collection of /api/v1 endpoints including time, IP detection, and country lists with flags, alongside a health check endpoint—suitable for testing or building widgets.
• Live Iranian Market Data: Automated background jobs fetch retail gold coin, bullion, currency exchange, and cryptocurrency rates in Iranian Rial from tgju.org and expose them under dedicated /api/v1 namespaces.
• Structured Responses: All responses follow the ApiResponse structure, providing JSON data with predictable error messages.
• Request Statistics: An in-memory counter tracks requests and persists them to the database every 60 seconds, showing usage metrics for each route.

Prerequisites

• Rust installation (recent stable version recommended)
• SQLite, used through the SeaORM driver—no separate installation needed unless you require command-line tools

Quick Start

1. Clone the repository and navigate into it
2. For first-time execution, the following command is sufficient to install dependencies and automatically create the database:

   cargo run

3. The service will be available at http://127.0.0.1:8080 (or values specified in .env)

ℹ️ Network access: The financial endpoints depend on reaching https://call3.tgju.org. Ensure outbound HTTPS access is allowed; otherwise the related responses will serve the most recent cached snapshot.

On first run, a .env file is created with the following default values, which you can modify as needed:

APP_DOMAIN=localhost
APP_FINAL_DOMAIN=localhost
APP_HOST=127.0.0.1
APP_PORT=80
APP_HTTPS=false
DATABASE_URL=sqlite://stats.db?mode=rwc

Configuration

• APP_HOST and APP_PORT: Specify the address and port for the service to listen on
• APP_DOMAIN: If present, displayed in startup logs to indicate if the service is behind a proxy or specific domain
• DATABASE_URL: SeaORM connection string; defaults to creating a local SQLite file

Main Routes

Route	Description	Example
/health	Service status, uptime, and usage statistics	GET /health
/api/v1/time	Current UTC time	GET /api/v1/time
/api/v1/time/{region}/{city}	Local time with custom timezone	GET /api/v1/time/asia/tehran
/api/v1/ip	Client IP detection from common headers	GET /api/v1/ip
/api/v1/country	List of country codes and names	GET /api/v1/country
/api/v1/country/full	Complete country information including currency, language, and flag	GET /api/v1/country/full
/api/v1/coin/ir	Retail prices for common Iranian gold coins with historical highs/lows	GET /api/v1/coin/ir
/api/v1/gold/ir	Retail bullion prices (18K, 24K, Mesghal, used gold) in Iran	GET /api/v1/gold/ir
/api/v1/currency/ir	Exchange rates for USD, EUR, AED, GBP, and TRY vs Iranian Rial	GET /api/v1/currency/ir
/api/v1/crypto/ir	Cryptocurrency prices in Iranian Rial for major assets	GET /api/v1/crypto/ir
/api/v1/flags/{code}	Retrieve flag SVG file by two-letter country code	GET /api/v1/flags/ir.svg

Financial Data Responses

All financial endpoints (/coin/ir, /gold/ir, /currency/ir, and /crypto/ir) return the shared ApiResponse envelope used by the rest of the service. The data payload contains keyed objects with the following fields:

{
  "current": 157500000,
  "highest": 158200000,
  "lowest": 156900000,
  "updated_at": "2024-03-10T14:35:00+03:30"
}

• current: Latest price reported by tgju.org (values are in Iranian Rial).
• highest / lowest: Session high and low values published by the source.
• updated_at: ISO-8601 timestamp (Asia/Tehran timezone) indicating when the quote was last refreshed.
• sync_at: Present at the root of each payload, showing when the service last fetched data from tgju.org.

Each endpoint focuses on a dedicated asset set:

• /coin/ir: Emami, Bahar, Half (Nim), Quarter (Rob), and Gerami Iranian gold coins.
• /gold/ir: 18K (750), 18K (740), 24K bullion, Mesghal weight, and used gold prices.
• /currency/ir: USD (Dollar), EUR, AED (Dirham), GBP (Pound Sterling), and TRY (Turkish Lira).
• /crypto/ir: Bitcoin, Ethereum, Binance Coin, Ripple (XRP), USD Coin, Dogecoin, and Tron.

Background jobs continuously refresh the cached dataset, ensuring quick responses even if the upstream service is temporarily unreachable.

Build and Deployment

• To build a production-ready release:

  cargo build --release

  The executable will be located at target/release/rest-api.ir and can be run on any Linux server with appropriate environment variables configured.
• Database migrations are managed through the migration subproject. They run via cargo run in the main directory and are automatically applied during application startup.

Contributing

This project is a work in progress focused on learning and growth. If you encounter bugs, have ideas, or want to propose new routes, please open an issue or submit a pull request. I welcome constructive feedback and suggestions.