Developer Menu 2/4

2. API Architecture

Eventiq provides a RESTful API primarily for the Flutter mobile applications (user and volunteer), with reusable endpoints for other clients.

Authentication Method

The API uses Laravel Sanctum for token-based authentication:

  1. Registration/Login: Users receive API tokens upon successful authentication
  2. Token Storage: Tokens are stored in personal_access_tokens table
  3. Middleware Protection: Protected routes use auth:sanctum middleware
  4. Token Management: Tokens are revoked on logout or security actions; new tokens are issued on next login

Base Endpoint Format

Base URL: https://your-domain.com/api
Authentication: Bearer Token (Sanctum)
Content-Type: application/json

API Structure

Important: Endpoint list below is the integration overview used by Eventiq clients. Exact paths/methods can differ by build customization. Always verify current route definitions in your Laravel API routes before extending.

Verified Source: routes/api.php in the Laravel project.

Public Endpoints (No Authentication)

GET  /api/categories                - Event categories
GET  /api/events                    - Event listing
GET  /api/event/details/{event}     - Event details
GET  /api/organizers                - Organizer list
GET  /api/organizer/details/{organizer} - Organizer profile
GET  /api/reviews                   - Organizer/event reviews
GET  /api/settings                  - App settings
GET  /api/filter-options            - Event filter options
GET  /api/all-languages             - Language list
GET  /api/event-tickets/{event}     - Event ticket types
GET  /api/gateways                  - Payment gateways
GET  /api/gateways/{id}             - Manual gateway details
GET  /api/google-map-api            - Google map JS proxy

Authentication Endpoints

POST /api/registration        - User registration
POST /api/account-activation - Account activation by email token
POST /api/login              - User login
POST /api/forgot-password    - Password reset request
POST /api/email-verification - Email verification
POST /api/reset-password     - Password reset confirmation

Protected Endpoints (Require Authentication)

User Management

GET  /api/user               - User profile
POST /api/update-profile     - Update profile
POST /api/change-password    - Change password
GET  /api/notifications      - Notification list
GET  /api/all-notifications/{id} - Notification details

Event Interactions

POST /api/event-favorite/{event} - Toggle favorite
POST /api/event-ticket/purchase/{event} - Create ticket purchase
POST /api/checkout-confirmation - Submit/confirm payment
POST /api/coupon-discount       - Apply coupon on purchase
GET  /api/my-tickets             - User's tickets
GET  /api/ticket-details/{id}    - Single ticket details
GET  /api/my-events              - User's events
GET  /api/my-favorite-events     - Favorite events
GET  /api/my-preference          - User preference categories
POST /api/set-preference         - Save preference categories

Social Features

POST /api/follow-organizer/{organizer}  - Follow organizer
POST /api/unfollow-organizer/{organizer} - Unfollow organizer
GET  /api/my-following-lists     - Following list
POST /api/review                 - Submit review

Chat System

GET  /api/chat-list              - Chat conversations
GET  /api/chat/{organizer_id}    - Chat messages
POST /api/send-message           - Send message

Volunteer Features

GET  /api/volunteer/dashboard    - Volunteer dashboard
GET  /api/volunteer/event-details/{event} - Event details for volunteers
GET  /api/volunteer/find-ticket/{ticket_id} - Find ticket by code
POST /api/volunteer/accept-ticket/{ticket_id} - Accept/check-in ticket
POST /api/volunteer/reject-ticket/{ticket_id} - Reject ticket
GET  /api/volunteer/all-events   - All assigned volunteer events

Flutter App Communication

The Flutter app communicates with the Laravel backend through:

  1. HTTP Client: Uses Dio or similar HTTP client library
  2. Token Storage: Securely stores Sanctum tokens locally
  3. Error Handling: Implements proper error handling for API responses
  4. Request Interceptors: Automatically adds authentication headers
  5. Response Models: Dart models matching JSON API responses

API Response Format

The structures below are the standard response pattern used by Eventiq API controllers/resources. Some framework-generated responses (for example, validation/auth middleware) may vary slightly.

Success Response Structure

{
  "status": true,
  "data": {
    // Response payload varies by endpoint
  },
  "message": "Operation successful"
}

Error Response Structure

{
  "status": false,
  "message": "Validation failed",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  }
}

Detailed Endpoint Specifications

Note: Sample payloads/IDs/timestamps below are illustrative and may differ from your deployment data shape.

Authentication Endpoints

POST /api/registration

Description: Register a new user account

Request Body
{
  "full_name": "John Doe",
  "register_type": "user",
  "email": "john@example.com",
  "username": "johndoe",
  "password": "securePassword123",
  "password_confirmation": "securePassword123",
  "ref_id": "optional_ref_code",
  "recaptcha_token": "optional_recaptcha_token"
}
Response (201 Created)
{
  "status": true,
  "data": {
    "user": {
      "id": "01H8X9Z2Y3W4K5M6N7P8Q9R0",
      "full_name": "John Doe",
      "email": "john@example.com",
      "username": "johndoe",
      "role": "user",
      "is_organizer": 0,
      "email_verified": false,
      "kyc_verified": false,
      "balance": "0.00000000",
      "average_rating": null,
      "created_at": "2025-03-05T14:52:00.000000Z",
      "updated_at": "2025-03-05T14:52:00.000000Z"
    },
    "token": "1|abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"
  },
  "message": "Registration successful"
}

POST /api/login

Description: Authenticate user and return access token

Implementation Note: If email verification is enabled and user is unverified, API may return a message to verify email before issuing token.

Request Body
{
  "email": "john@example.com",
  "password": "securePassword123"
}
Response (200 OK)
{
  "status": true,
  "data": {
    "user": {
      "id": "01H8X9Z2Y3W4K5M6N7P8Q9R0",
      "full_name": "John Doe",
      "email": "john@example.com",
      "username": "johndoe",
      "role": "user",
      "is_organizer": 0,
      "email_verified": true,
      "balance": "150.75000000"
    },
    "token": "1|abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
    "token_type": "Bearer"
  },
  "message": "Login successful"
}

Event Endpoints

GET /api/events

Description: Retrieve paginated list of events with filtering options

Query Parameters
GET /api/events?page=1&per_page=20&category=technology&status=active&featured=true&search=conference
Response (200 OK)
{
  "status": true,
  "data": {
    "events": [
      {
        "id": "01H8X9Z2Y3W4K5M6N7P8Q9R1",
        "name": "Tech Conference 2025",
        "slug": "tech-conference-2025",
        "status": "active",
        "start_date": "2025-06-15T09:00:00.000000Z",
        "end_date": "2025-06-17T18:00:00.000000Z",
        "seating_capacity": 500,
        "price": "299.99",
        "is_featured": 1,
        "is_free": 0,
        "view": 1250,
        "banner": "events/banners/tech-conference-2025.jpg",
        "address": "San Francisco Convention Center, CA",
        "organizer": {
          "id": "01H8X9Z2Y3W4K5M6N7P8Q9R2",
          "full_name": "Tech Events Inc",
          "username": "techevents",
          "average_rating": "4.8"
        },
        "ticket_types": [
          {
            "id": "01H8X9Z2Y3W4K5M6N7P8Q9R3",
            "name": "Early Bird",
            "price": "199.99",
            "number_of_tickets": 100,
            "is_free": 0
          }
        ],
        "created_at": "2025-03-01T10:00:00.000000Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 150,
      "last_page": 8,
      "has_more": true
    },
    "filters": {
      "categories": ["technology", "business", "education"],
      "statuses": ["active", "upcoming"]
    }
  },
  "message": "Events retrieved successfully"
}

GET /api/event/details/{event}

Description: Retrieve detailed information for a specific event

Response (200 OK)
{
  "status": true,
  "data": {
    "event": {
      "id": "01H8X9Z2Y3W4K5M6N7P8Q9R1",
      "name": "Tech Conference 2025",
      "slug": "tech-conference-2025",
      "status": "active",
      "start_date": "2025-06-15T09:00:00.000000Z",
      "end_date": "2025-06-17T18:00:00.000000Z",
      "seating_capacity": 500,
      "price": "299.99",
      "is_featured": 1,
      "is_free": 0,
      "view": 1250,
      "banner": "events/banners/tech-conference-2025.jpg",
      "details": "Join us for the biggest tech conference of the year...",
      "address": "San Francisco Convention Center, CA",
      "organizer": {
        "id": "01H8X9Z2Y3W4K5M6N7P8Q9R2",
        "full_name": "Tech Events Inc",
        "username": "techevents",
        "email": "contact@techevents.com",
        "phone": "+1234567890",
        "average_rating": "4.8",
        "is_verified": true
      },
      "ticket_types": [
        {
          "id": "01H8X9Z2Y3W4K5M6N7P8Q9R3",
          "name": "Early Bird",
          "price": "199.99",
          "number_of_tickets": 100,
          "is_free": 0,
          "have_discount": 1,
          "discount_type": "percentage",
          "discount_value": "33",
          "purchase_start_date": "2025-03-01",
          "purchase_end_date": "2025-05-31"
        },
        {
          "id": "01H8X9Z2Y3W4K5M6N7P8Q9R4",
          "name": "VIP",
          "price": "599.99",
          "number_of_tickets": 50,
          "is_free": 0
        }
      ],
      "reviews": [
        {
          "id": "01H8X9Z2Y3W4K5M6N7P8Q9R5",
          "user": {
            "full_name": "Jane Smith",
            "username": "janesmith"
          },
          "rating": 5,
          "comment": "Amazing conference! Great speakers and networking.",
          "created_at": "2025-02-28T15:30:00.000000Z"
        }
      ],
      "is_favorited": false,
      "total_tickets_sold": 275,
      "created_at": "2025-03-01T10:00:00.000000Z"
    }
  },
  "message": "Event"
}

Ticket Purchase Endpoints

POST /api/event-ticket/purchase/{event}

Description: Purchase tickets for an event

Request Body
{
  "selected_date": "2025-06-15",
  "tickets": [
    {
      "id": "01H8X9Z2Y3W4K5M6N7P8Q9R3",
      "name": "Early Bird",
      "price": 199.99,
      "quantity": 2
    },
    {
      "id": "01H8X9Z2Y3W4K5M6N7P8Q9R4",
      "name": "VIP",
      "price": 599.99,
      "quantity": 1
    }
  ],
  "total_amount": 999.97
}
Response (201 Created / 200 for free events)
{
  "status": true,
  "message": "Ticket purchase created, proceed to payment",
  "data": {
    "id": "01H8X9Z2Y3W4K5M6N7P8Q9R6",
    "trx": "TRX-20250305-001",
    "user_id": "01H8X9Z2Y3W4K5M6N7P8Q9R0",
    "event_id": "01H8X9Z2Y3W4K5M6N7P8Q9R1",
    "total_quantity": 3,
    "sub_total": "999.97",
    "final_amount": "1029.96",
    "status": "pending"
  }
}

User Management Endpoints

GET /api/user

Description: Retrieve current user's profile information

Response (200 OK)
{
  "status": true,
  "data": {
    "user": {
      "id": "01H8X9Z2Y3W4K5M6N7P8Q9R0",
      "full_name": "John Doe",
      "email": "john@example.com",
      "username": "johndoe",
      "phone": "+1234567890",
      "image": "users/avatars/johndoe.jpg",
      "role": "user",
      "is_organizer": 0,
      "email_verified": true,
      "sms_verified": true,
      "kyc_verified": false,
      "balance": "150.75000000",
      "average_rating": null,
      "social": {
        "twitter": "@johndoe",
        "linkedin": "linkedin.com/in/johndoe"
      },
      "tags": ["technology", "business"],
      "stats": {
        "events_attended": 12,
        "events_organized": 0,
        "reviews_given": 8,
        "following_count": 15
      },
      "created_at": "2025-01-15T10:00:00.000000Z",
      "updated_at": "2025-03-05T14:52:00.000000Z"
    }
  },
  "message": "User profile retrieved successfully"
}

POST /api/update-profile

Description: Update user profile information

Request Body
{
  "full_name": "John Smith Doe",
  "phone": "+1234567890",
  "image": "base64_encoded_image_data",
  "social": {
    "twitter": "@johnsmithdoe",
    "linkedin": "linkedin.com/in/johnsmithdoe",
    "website": "johnsmithdoe.com"
  },
  "tags": ["technology", "business", "startup"]
}
Response (200 OK)
{
  "status": true,
  "data": {
    "user": {
      "id": "01H8X9Z2Y3W4K5M6N7P8Q9R0",
      "full_name": "John Smith Doe",
      "email": "john@example.com",
      "username": "johndoe",
      "phone": "+1234567890",
      "image": "users/avatars/johndoe_updated.jpg",
      "social": {
        "twitter": "@johnsmithdoe",
        "linkedin": "linkedin.com/in/johnsmithdoe",
        "website": "johnsmithdoe.com"
      },
      "tags": ["technology", "business", "startup"],
      "updated_at": "2025-03-05T14:55:00.000000Z"
    }
  },
  "message": "Profile updated successfully"
}

Social Features Endpoints

POST /api/event-favorite/{id}

Description: Toggle favorite status for an event

Response (200 OK)
{
  "status": true,
  "data": {
    "event_id": "01H8X9Z2Y3W4K5M6N7P8Q9R1",
    "is_favorited": true,
    "total_favorites": 342
  },
  "message": "Event added to favorites"
}

POST /api/review

Description: Submit a review for an attended event

Request Body
{
  "event_id": "01H8X9Z2Y3W4K5M6N7P8Q9R1",
  "rating": 5,
  "comment": "Excellent conference with great networking opportunities!"
}
Response (201 Created)
{
  "status": true,
  "data": {
    "review": {
      "id": "01H8X9Z2Y3W4K5M6N7P8Q9R9",
      "user": {
        "id": "01H8X9Z2Y3W4K5M6N7P8Q9R0",
        "full_name": "John Doe",
        "username": "johndoe",
        "image": "users/avatars/johndoe.jpg"
      },
      "event_id": "01H8X9Z2Y3W4K5M6N7P8Q9R1",
      "rating": 5,
      "comment": "Excellent conference with great networking opportunities!",
      "created_at": "2025-03-05T14:52:00.000000Z",
      "updated_at": "2025-03-05T14:52:00.000000Z"
    }
  },
  "message": "Review submitted successfully"
}

Error Handling and Status Codes

HTTP Status Codes

Status Code Meaning Use Cases
200 OK Request successful GET requests, successful updates
201 Created Resource created POST requests creating resources
204 No Content Success, no response body DELETE operations
400 Bad Request Invalid request Malformed JSON, invalid parameters
401 Unauthorized Authentication required Missing/invalid token
403 Forbidden Insufficient permissions Access denied to resource
404 Not Found Resource not found Invalid event/user ID
422 Unprocessable Entity Validation failed Invalid form data
429 Too Many Requests Rate limit exceeded API rate limiting
500 Server Error Internal server error Unexpected server issues

Error Response Examples

Validation Error (422)

{
  "status": false,
  "message": "Validation failed",
  "errors": {
    "email": [
      "The email field is required.",
      "The email must be a valid email address."
    ],
    "password": [
      "The password must be at least 8 characters.",
      "The password must contain at least one uppercase letter."
    ],
    "tickets.0.quantity": [
      "The quantity must be at least 1.",
      "Only 5 tickets remaining for this type."
    ]
  }
}

Authentication Error (401)

{
  "status": false,
  "message": "Unauthenticated.",
  "errors": null
}

Not Found Error (404)

{
  "status": false,
  "message": "Event not found.",
  "errors": null
}

Rate Limit Error (429)

{
  "status": false,
  "message": "Too many requests. Try again later.",
  "errors": null
}

Request Headers

Required Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer {sanctum_token}   // required for protected endpoints only

Optional Headers

X-Requested-With: XMLHttpRequest
X-Client-Version: 1.0.0
X-Platform: android|ios|web
X-Device-ID: unique_device_identifier

Response Headers

Content-Type: application/json
X-RateLimit-Limit: 1000                // if rate limiting is enabled
X-RateLimit-Remaining: 999             // if rate limiting is enabled
X-RateLimit-Reset: 1646433600          // if rate limiting is enabled
X-Request-ID: req_abc123def456         // if request-id middleware is enabled
X-API-Version: v1                      // if version header is implemented

API Versioning

Default Eventiq routes are typically exposed under /api. If you introduce breaking API changes, apply an explicit versioning strategy:

  • URL Versioning (recommended for major changes): /api/v1/events, /api/v2/events
  • Header Versioning (optional): Accept: application/vnd.eventiq.v1+json
  • Backward Compatibility Rule: keep old versions active until mobile apps are updated

API Layers

  1. Route definition to controller method (routes/api.php and/or module route files)
  2. Request validation (FormRequest classes or inline validator rules)
  3. Business/data logic (models + service classes)
  4. JSON response (status, message, data)