# Shahar Backend API

Django REST API implementation for the Reality Potential & Summary API specification (v1.0, Aug 27 2026).

## Setup

```bash
uv sync
cp .env.example .env   # or keep your existing .env
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver
```

The project uses MySQL through the `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `DB_HOST`, and `DB_PORT` environment variables.

## API authentication

All API endpoints under `/api/v1/` require:

```http
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

Create a key from Django shell:

```python
from api.models import APIKey
key, raw_key = APIKey.create_key("Website client", "standard")
print(raw_key)  # save this value; only its hash is stored
```

Standard keys are throttled at 60 requests/minute and enterprise keys at 600 requests/minute. The API returns the rate-limit values in response headers.

## Endpoints

- `GET /api/v1/cities/<city>/wards/`
- `GET /api/v1/spot-detail/<spot_id>/`
- `GET /api/v1/leaderboard/?city=Pune&period=most-improved`
- `GET /api/v1/reality-potential/`
- `GET /api/v1/summary/`

The existing `/api/city/<city>/wards/` route is retained for backwards compatibility.

## Reality Potential filters

`page`, `limit` (max 20), `tags` (CSV), `shortlisted`, `spot_name`, `from_date`, `to_date`.

## Summary filters

`from_date`, `to_date`, `region`.

## Sample data for API testing

Create a small test dataset matching the API documentation examples:

```bash
python manage.py seed_sample_data
```

The command creates sample Pune and Mumbai cities, wards, Shahar spots, Anchor spots, tags, images, engagements, and a fresh Standard API key. The generated API key is printed once to the terminal because only its hash is stored in the database.

To recreate the sample dataset:

```bash
python manage.py seed_sample_data --reset
```

To test the Enterprise rate limit configuration:

```bash
python manage.py seed_sample_data --reset --plan enterprise
```

Example request:

```bash
curl -X GET "http://127.0.0.1:8000/api/v1/reality-potential/?shortlisted=true&limit=20" \\
  -H "Authorization: Bearer <KEY_PRINTED_BY_COMMAND>" \\
  -H "Content-Type: application/json"
```
