# Property API Documentation

## Overview
This API provides access to property listings with various filtering and search capabilities. All endpoints are public and do not require authentication.

## Base URL
```
/api/properties
```

## Endpoints

### 1. Get All Properties (Paginated)
**GET** `/api/properties`

Returns a paginated list of active properties with filtering options.

#### Query Parameters
- `type` (optional): Filter by property type (villa, chalet, townhouse, apartment, penthouse, duplex)
- `bedrooms` (optional): Minimum number of bedrooms
- `bathrooms` (optional): Minimum number of bathrooms
- `min_area` (optional): Minimum area in square meters
- `max_area` (optional): Maximum area in square meters
- `search` (optional): Search in title and short description
- `per_page` (optional): Number of items per page (default: 12)

#### Example Request
```bash
GET /api/properties?type=villa&bedrooms=3&per_page=10
```

#### Example Response
```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "title": "Luxury Villa",
            "short_description": "Beautiful villa with ocean view",
            "card_image": "http://example.com/storage/properties/villa1.jpg",
            "area": 250.50,
            "formatted_area": "250.50 m²",
            "bedrooms": 4,
            "bathrooms": 3,
            "type": "villa",
            "type_name": "Villa",
            "display_on_mobile": true,
            "display_on_homepage": true,
            "created_at": "2024-01-15T10:30:00.000000Z",
            "updated_at": "2024-01-15T10:30:00.000000Z"
        }
    ],
    "pagination": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 10,
        "total": 50,
        "from": 1,
        "to": 10
    },
    "message": "Properties retrieved successfully"
}
```

---

### 2. Get Single Property Details
**GET** `/api/properties/{id}`

Returns detailed information about a specific property including full description and gallery images.

**⚠️ Authentication Required**: This endpoint requires a valid Bearer token.

#### Headers
```
Authorization: Bearer {your-token}
```

#### Path Parameters
- `id` (required): Property ID

#### Example Request
```bash
curl -X GET "http://your-domain.com/api/properties/1" \
  -H "Authorization: Bearer {your-token}" \
  -H "Accept: application/json"
```

#### Example Response
```json
{
    "success": true,
    "data": {
        "id": 1,
        "title": "Luxury Villa",
        "short_description": "Beautiful villa with ocean view",
        "card_image": "http://example.com/storage/properties/villa1.jpg",
        "area": 250.50,
        "formatted_area": "250.50 m²",
        "bedrooms": 4,
        "bathrooms": 3,
        "type": "villa",
        "type_name": "Villa",
        "display_on_mobile": true,
        "display_on_homepage": true,
        "created_at": "2024-01-15T10:30:00.000000Z",
        "updated_at": "2024-01-15T10:30:00.000000Z",
        "full_description": "<p>This luxurious villa offers stunning ocean views and modern amenities...</p>",
        "gallery": [
            "http://example.com/storage/properties/gallery1.jpg",
            "http://example.com/storage/properties/gallery2.jpg",
            "http://example.com/storage/properties/gallery3.jpg"
        ],
        "is_active": true,
        "sort_order": 1
    },
    "message": "Property retrieved successfully"
}
```

#### Error Response (Property Not Found)
```json
{
    "success": false,
    "message": "Property not found"
}
```

#### Error Response (Unauthorized)
```json
{
    "message": "Unauthenticated."
}
```

---

### 3. Get Mobile Properties
**GET** `/api/properties/mobile/list`

Returns properties configured for mobile display.

#### Query Parameters
- `type` (optional): Filter by property type
- `limit` (optional): Number of properties to return (default: 10)

#### Example Request
```bash
GET /api/properties/mobile/list?limit=5
```

#### Example Response
```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "title": "Luxury Villa",
            "short_description": "Beautiful villa with ocean view",
            "card_image": "http://example.com/storage/properties/villa1.jpg",
            "area": 250.50,
            "formatted_area": "250.50 m²",
            "bedrooms": 4,
            "bathrooms": 3,
            "type": "villa",
            "type_name": "Villa",
            "display_on_mobile": true,
            "display_on_homepage": true,
            "created_at": "2024-01-15T10:30:00.000000Z",
            "updated_at": "2024-01-15T10:30:00.000000Z"
        }
    ],
    "message": "Mobile properties retrieved successfully"
}
```

---

### 4. Get Homepage Properties
**GET** `/api/properties/homepage/list`

Returns properties configured for homepage display.

#### Query Parameters
- `type` (optional): Filter by property type
- `limit` (optional): Number of properties to return (default: 6)

#### Example Request
```bash
GET /api/properties/homepage/list?type=villa&limit=4
```

#### Example Response
```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "title": "Luxury Villa",
            "short_description": "Beautiful villa with ocean view",
            "card_image": "http://example.com/storage/properties/villa1.jpg",
            "area": 250.50,
            "formatted_area": "250.50 m²",
            "bedrooms": 4,
            "bathrooms": 3,
            "type": "villa",
            "type_name": "Villa",
            "display_on_mobile": true,
            "display_on_homepage": true,
            "created_at": "2024-01-15T10:30:00.000000Z",
            "updated_at": "2024-01-15T10:30:00.000000Z"
        }
    ],
    "message": "Homepage properties retrieved successfully"
}
```

---

### 5. Get Property Types
**GET** `/api/properties/types`

Returns all available property types.

#### Example Request
```bash
GET /api/properties/types
```

#### Example Response
```json
{
    "success": true,
    "data": {
        "villa": "Villa",
        "chalet": "Chalet",
        "townhouse": "Townhouse",
        "apartment": "Apartment",
        "penthouse": "Penthouse",
        "duplex": "Duplex"
    },
    "message": "Property types retrieved successfully"
}
```

---

### 6. Get Property Statistics
**GET** `/api/properties/statistics`

Returns comprehensive statistics about properties.

#### Example Request
```bash
GET /api/properties/statistics
```

#### Example Response
```json
{
    "success": true,
    "data": {
        "total": 50,
        "by_type": {
            "villa": {
                "name": "Villa",
                "count": 20
            },
            "apartment": {
                "name": "Apartment",
                "count": 15
            },
            "chalet": {
                "name": "Chalet",
                "count": 10
            },
            "townhouse": {
                "name": "Townhouse",
                "count": 5
            }
        },
        "total_bedrooms": 150,
        "total_bathrooms": 120,
        "average_area": 200.50,
        "mobile_display": 30,
        "homepage_display": 25
    },
    "message": "Property statistics retrieved successfully"
}
```

---

### 7. Search Properties
**GET** `/api/properties/search`

Search properties by query string.

**⚠️ Authentication Required**: This endpoint requires a valid Bearer token.

#### Headers
```
Authorization: Bearer {your-token}
```

#### Query Parameters
- `query` (required): Search term (minimum 2 characters)

#### Example Request
```bash
curl -X GET "http://your-domain.com/api/properties/search?query=luxury villa" \
  -H "Authorization: Bearer {your-token}" \
  -H "Accept: application/json"
```

#### Example Response
```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "title": "Luxury Villa",
            "short_description": "Beautiful villa with ocean view",
            "card_image": "http://example.com/storage/properties/villa1.jpg",
            "area": 250.50,
            "formatted_area": "250.50 m²",
            "bedrooms": 4,
            "bathrooms": 3,
            "type": "villa",
            "type_name": "Villa",
            "display_on_mobile": true,
            "display_on_homepage": true,
            "created_at": "2024-01-15T10:30:00.000000Z",
            "updated_at": "2024-01-15T10:30:00.000000Z"
        }
    ],
    "message": "Search results retrieved successfully"
}
```

#### Error Response (Unauthorized)
```json
{
    "message": "Unauthenticated."
}
```

---

## Data Models

### Property Object (Summary)
```json
{
    "id": "integer",
    "title": "string",
    "short_description": "string",
    "card_image": "string (URL)",
    "area": "decimal",
    "formatted_area": "string",
    "bedrooms": "integer",
    "bathrooms": "integer",
    "type": "string",
    "type_name": "string",
    "display_on_mobile": "boolean",
    "display_on_homepage": "boolean",
    "created_at": "datetime (ISO)",
    "updated_at": "datetime (ISO)"
}
```

### Property Object (Detailed)
```json
{
    "id": "integer",
    "title": "string",
    "short_description": "string",
    "card_image": "string (URL)",
    "area": "decimal",
    "formatted_area": "string",
    "bedrooms": "integer",
    "bathrooms": "integer",
    "type": "string",
    "type_name": "string",
    "display_on_mobile": "boolean",
    "display_on_homepage": "boolean",
    "created_at": "datetime (ISO)",
    "updated_at": "datetime (ISO)",
    "full_description": "string (HTML)",
    "gallery": "array of strings (URLs)",
    "is_active": "boolean",
    "sort_order": "integer"
}
```

## Error Responses

### Standard Error Format
```json
{
    "success": false,
    "message": "Error description"
}
```

### Common HTTP Status Codes and Responses

#### 404 - Not Found
```json
{
    "success": false,
    "message": "Property not found"
}
```

#### 401 - Unauthorized
```json
{
    "success": false,
    "message": "Unauthenticated"
}
```

#### 403 - Forbidden
```json
{
    "success": false,
    "message": "Unauthorized"
}
```

#### 422 - Validation Error
```json
{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "field_name": [
            "The field name is required."
        ]
    }
}
```

#### 500 - Internal Server Error (Development)
```json
{
    "success": false,
    "message": "Error message",
    "exception": "ExceptionClass",
    "file": "path/to/file.php",
    "line": 123
}
```

#### 500 - Internal Server Error (Production)
```json
{
    "success": false,
    "message": "Internal server error"
}
```

## Usage Examples

### JavaScript/Fetch
```javascript
// Get all properties (public)
fetch('/api/properties')
    .then(response => response.json())
    .then(data => console.log(data));

// Get single property (authenticated)
fetch('/api/properties/1', {
    headers: {
        'Authorization': 'Bearer ' + yourToken,
        'Accept': 'application/json'
    }
})
.then(response => response.json())
.then(data => console.log(data));

// Search properties (authenticated)
fetch('/api/properties/search?query=villa', {
    headers: {
        'Authorization': 'Bearer ' + yourToken,
        'Accept': 'application/json'
    }
})
.then(response => response.json())
.then(data => console.log(data));
```

### cURL
```bash
# Get all properties (public)
curl -X GET "http://your-domain.com/api/properties"

# Get single property (authenticated)
curl -X GET "http://your-domain.com/api/properties/1" \
  -H "Authorization: Bearer {your-token}" \
  -H "Accept: application/json"

# Search properties (authenticated)
curl -X GET "http://your-domain.com/api/properties/search?query=villa" \
  -H "Authorization: Bearer {your-token}" \
  -H "Accept: application/json"
```

### PHP
```php
// Get all properties (public)
$response = file_get_contents('http://your-domain.com/api/properties');
$data = json_decode($response, true);

// Get single property (authenticated)
$context = stream_context_create([
    'http' => [
        'header' => [
            'Authorization: Bearer ' . $yourToken,
            'Accept: application/json'
        ]
    ]
]);
$response = file_get_contents('http://your-domain.com/api/properties/1', false, $context);
$data = json_decode($response, true);
```

## Notes

1. **Authentication**: 
   - **Public Endpoints**: Property listing, mobile properties, homepage properties, types, and statistics don't require authentication
   - **Protected Endpoints**: Single property details and search require valid Bearer token authentication
2. **Caching**: Consider implementing caching for better performance
3. **Rate Limiting**: Implement rate limiting for production use
4. **Image URLs**: All image URLs are absolute URLs pointing to your storage
5. **HTML Content**: The `full_description` field contains HTML content from the rich text editor
6. **Active Properties**: Only active properties are returned by default
7. **Pagination**: Use pagination parameters for large datasets 