Dari API

REST API backend for dari.dz — an Algerian real estate listing platform for agencies and private sellers.

Tech Stack

Layer	Technology
Framework	FastAPI
Database	PostgreSQL (via asyncpg)
ORM	SQLAlchemy 2.x (async)
Migrations	Alembic
Auth	JWT (python-jose)
Image storage	Cloudinary or local filesystem
Validation	Pydantic v2

Features

• Dual JWT authentication — independent flows for agencies and private users
• Full listing CRUD with pagination, filtering, and map marker endpoints
• Image upload per listing (Cloudinary or local fallback)
• Agency profile management with logo and cover photo
• View counter with atomic SQL updates
• Seed script with 5 agencies, 2 users, and 21+ listings across Algeria

Project Structure

dari-api/
├── app/
│   ├── auth/
│   │   ├── dependencies.py   # get_current_agency / get_current_user / get_current_any
│   │   └── jwt.py            # token creation and decoding
│   ├── models/
│   │   ├── agency.py
│   │   ├── listing.py        # Listing + ListingImage
│   │   └── user.py
│   ├── routers/
│   │   ├── agencies.py
│   │   ├── auth.py
│   │   ├── listings.py
│   │   └── users.py
│   ├── schemas/
│   │   ├── agency.py
│   │   ├── listing.py
│   │   └── user.py
│   ├── utils/
│   │   └── images.py         # Cloudinary / local upload
│   ├── config.py
│   ├── database.py
│   └── main.py
├── alembic/
├── seed.py
├── requirements.txt
└── .env

Getting Started

Prerequisites

• Python 3.11+
• PostgreSQL (Docker recommended)

1. Clone the repository

git clone <repo-url>
cd dari-api

2. Create a virtual environment

python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Start PostgreSQL with Docker

docker run -d --name dari-db -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=dari_db -p 5432:5432 postgres:16

5. Configure environment variables

Create a .env file in the project root:

DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/dari_db

JWT_SECRET=your-secret-key-here
JWT_ALGORITHM=HS256
AGENCY_TOKEN_EXPIRE_DAYS=7
USER_TOKEN_EXPIRE_DAYS=30

# Image storage — set USE_LOCAL_STORAGE=false to use Cloudinary
USE_LOCAL_STORAGE=true
UPLOAD_DIR=./uploads

# Cloudinary (only required when USE_LOCAL_STORAGE=false)
CLOUDINARY_CLOUD_NAME=
CLOUDINARY_API_KEY=
CLOUDINARY_API_SECRET=

6. Run database migrations

alembic upgrade head

7. (Optional) Seed the database

python seed.py

8. Start the server

uvicorn app.main:app --reload

The API will be available at http://localhost:8000.
Interactive docs: http://localhost:8000/docs

API Reference

Auth

Method	Endpoint	Description
POST	/auth/login	Agency login — returns JWT
POST	/users/register	User registration — returns JWT
POST	/users/login	User login — returns JWT

Listings

Method	Endpoint	Auth	Description
GET	/listings	—	Paginated listing search with filters
GET	/listings/recent	—	Latest N active listings
GET	/listings/promoted	—	Promoted listings
GET	/listings/markers	—	Map markers with coordinates
GET	/listings/by-ids	—	Fetch listings by comma-separated IDs
GET	/listings/{id}	—	Full listing detail
POST	/listings	Agency or User	Create a listing
PUT	/listings/{id}	Owner	Update a listing
DELETE	/listings/{id}	Owner	Delete a listing
POST	/listings/{id}/view	—	Increment view counter
POST	/listings/{id}/images	Owner	Upload images

Agencies

Method	Endpoint	Auth	Description
GET	/agencies	—	List all agencies
GET	/agencies/featured	—	Featured agencies
GET	/agencies/{id}	—	Agency detail
GET	/agencies/slug/{slug}	—	Agency by slug
PUT	/agencies/{id}	Agency	Update agency profile
POST	/agencies/{id}/logo	Agency	Upload logo
POST	/agencies/{id}/cover	Agency	Upload cover photo

Users

Method	Endpoint	Auth	Description
GET	/users/me	User	Current user profile
GET	/users/me/listings	User	Listings by current user

Query Parameters — GET /listings

Param	Type	Description
listing_type	string	vente or location
property_type	string	appartement, villa, terrain, etc.
publisher_type	string	agence or particulier
wilaya	string	Exact wilaya name
location_query	string	Partial match on city or wilaya
min_price	int	Minimum price
max_price	int	Maximum price
min_surface	int	Minimum surface in m²
page	int	Page number (default: 1)
per_page	int	Results per page (default: 12, max: 50)

Authentication

All protected endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <token>

Tokens are obtained from the login endpoints. Agency tokens expire after 7 days, user tokens after 30 days.

Environment Variables

Variable	Default	Description
DATABASE_URL	—	PostgreSQL connection string (asyncpg)
JWT_SECRET	change-me-in-production	Secret key for signing JWTs
JWT_ALGORITHM	HS256	JWT signing algorithm
AGENCY_TOKEN_EXPIRE_DAYS	7	Agency token TTL in days
USER_TOKEN_EXPIRE_DAYS	30	User token TTL in days
USE_LOCAL_STORAGE	true	Use local filesystem instead of Cloudinary
UPLOAD_DIR	./uploads	Local upload directory
CLOUDINARY_CLOUD_NAME	—	Cloudinary cloud name
CLOUDINARY_API_KEY	—	Cloudinary API key
CLOUDINARY_API_SECRET	—	Cloudinary API secret