diff --git a/README.md b/README.md index b4d92fd..0f44e18 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,13 @@ # 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. If you have ideas or suggestions, I'd be happy to receive pull requests. +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](https://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. @@ -22,6 +23,8 @@ This project is a small web service developed primarily for learning and experim ``` 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: ```env APP_DOMAIN=localhost @@ -46,8 +49,38 @@ DATABASE_URL=sqlite://stats.db?mode=rwc | `/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: + +```json +{ + "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: ```bash