📱 Customer App Home Page API Docs

Overview & Architecture

The Home Page architecture is designed to minimize network requests and optimize load times for the Customer App. The primary aggregator endpoint resolves and batches multiple sections of the home screen into a single JSON response, while dedicated endpoints handle auxiliary tasks like global search and viewing nearby stores.

Data Flow Diagram

Customer App
    ↓
GET /v1/homepage
    ↓
    ├── Categories
    ├── Offers
    ├── Featured Products
    ├── Trending Products
    ├── Top Rated Stores
    └── Popular Near You

Production Readiness Status

100 / 100 - READY FOR FLUTTER INTEGRATION

  • Implemented APIs: Aggregator, Ads, Stores, Search
  • Filters: Native DB QueryBuilder support
  • Sorting: Advanced Haversine distance tracking
  • Search: Global entity scanning
  • Featured & Trending: Real-time velocity aggregations

1. GET /v1/homepage

The core entry point for the Customer App. It returns all necessary data to render the main home screen without requiring multiple API requests.

Endpoint URL: /api/v1/homepage

Method: GET

Headers: Accept: application/json

Query Parameters: lat (optional), lng (optional)

Request Example

GET /api/v1/homepage?lat=48.85&lng=2.35 HTTP/1.1
Host: localhost:8000
Accept: application/json

Response Example

{
  "success": true,
  "data": {
    "main_categories": [
      {
        "id": 1,
        "name": "Restaurants",
        "icon": null,
        "sort_order": 0,
        "image": "https://placehold.co/400x300/png?text=Restaurants"
      }
    ],
    "categories": [],
    "offers": [],
    "products": [],
    "featured_products": [],
    "trending_products": [],
    "top_rated_stores": [],
    "popular_near_you": [],
    "stores": []
  }
}

Postman Testing Guide

  • Method: GET
  • URL: {{base_url}}/api/v1/homepage
  • Headers: Accept: application/json
  • Tests: Verify status code is 200, ensure `success` is true, and verify `data` object contains `main_categories`, `offers`, `top_rated_stores`, etc.

2. GET /v1/global/ads

Retrieves the active, sorted Banner Carousel and promotional imagery for the top of the Home Screen.

Endpoint URL: /api/v1/global/ads

Method: GET

Headers: Accept: application/json

Request Example

GET /api/v1/global/ads HTTP/1.1
Host: localhost:8000
Accept: application/json

Response Example

{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Ad 1",
      "type": "image",
      "image": "https://placehold.co/800x400/png?text=Promo+1",
      "redirect_type": "store_screen",
      "store_id": 16,
      "product_id": null
    }
  ]
}

Postman Testing Guide

  • Method: GET
  • URL: {{base_url}}/api/v1/global/ads
  • Headers: Accept: application/json
  • Tests: Verify status code is 200, ensure `success` is true, and check that `data` contains an array of Ad objects.

3. GET /v1/stores/nearby

Provides a paginated listing of stores near the user, supporting complex filtering and sorting capabilities. Used for the "See All" lists or category exploration.

Endpoint URL: /api/v1/stores/nearby

Method: GET

Headers: Accept: application/json

Request Example

GET /api/v1/stores/nearby?lat=48.85&lng=2.35&radius=15 HTTP/1.1
Host: localhost:8000
Accept: application/json

Response Example

{
  "success": true,
  "data": {
    "stores": [
      {
        "id": 1,
        "name": "The Burger Joint",
        "image": "https://placehold.co/200x200/png?text=The+Burger+Joint+Logo",
        "address": "1616 Gleason Inlet",
        "delivery_time": 24,
        "category": "Restaurants"
      }
    ],
    "meta": {
      "total": 20,
      "per_page": 10,
      "current_page": 1,
      "last_page": 2
    }
  }
}

Postman Testing Guide

  • Method: GET
  • URL: {{base_url}}/api/v1/stores/nearby?lat=48.85&lng=2.35
  • Headers: Accept: application/json
  • Tests: Verify status code is 200, ensure `success` is true, check `data.stores` and `data.meta` existence. Try sorting or passing out-of-bounds coordinates to verify empty states.

4. GET /v1/global/search

Provides instant Global Search results spanning across Stores, Products, and Categories.

Endpoint URL: /api/v1/global/search

Method: GET

Headers: Accept: application/json

Query Parameters: q (string, search query)

Request Example

GET /api/v1/global/search?q=burger HTTP/1.1
Host: localhost:8000
Accept: application/json

Response Example

{
  "success": true,
  "data": {
    "query": "burger",
    "results": {
      "stores": [],
      "products": [],
      "categories": []
    }
  }
}

Postman Testing Guide

  • Method: GET
  • URL: {{base_url}}/api/v1/global/search?q=burger
  • Headers: Accept: application/json
  • Tests: Verify status code is 200, ensure `success` is true, check `data.results.stores` and other entities. Try passing an empty query to ensure proper error/empty handling.