Overview

Overview

The Mobile App Boilerplate follows a unified REST API specification to ensure seamless integration between the Flutter application and any supported backend.

While the reference implementation is currently built on Laravel, the API contract is strictly followed across all upcoming adapters (like Hono) to maintain consistency and allow for easy backend switching without modifying the mobile app's networking layer.

Backend Support

Our goal is to provide flexibility in your choice of technology while keeping the mobile client logic unchanged:

• Laravel (Ready): The full-featured, production-ready PHP implementation using Sanctum.
• Hono & Tanstack Start (Coming Soon): Lightweight and high-performance TypeScript/Bun implementation.
• Other Adapters (Planned): Additional providers that adhere to the same API schema.

Base Configuration

Regardless of the chosen backend, all requests follow this standard:

• Path Versioning: All endpoints are prefixed with /api/v1.
• Headers:
  • Content-Type: application/json
  • Accept: application/json

Authentication Standard

The API architecture standardizes on Bearer Token Authentication for secure session management.

• Bearer Tokens: Most protected endpoints require a valid token in the Authorization header.
• Unified Flow: Authentication logic (Login, Register, Social Auth) returns a consistent payload containing the user object and the access token.
• Granular Scopes: All backends implement "abilities" or "scopes" (e.g., user:read, notifications:update) to restrict token permissions.

Response Consistency

A core principle of this boilerplate is that every backend implementation must return identical JSON structures. This ensures the Flutter app's data models remain stable across environments.

Success Response

{
  "success": true,
  "message": "Optional success message",
  "data": { ... }
}

Error Response

Standard HTTP status codes are used across all implementations, following a unified error format:

• 401 Unauthorized: Missing or invalid token.
• 422 Unprocessable Entity: Validation failed.
• 429 Too Many Requests: Rate limit exceeded.

Example Validation Error:

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The provided credentials are incorrect."]
  }
}

Next Steps

Explore the detailed API Routes to see the unified endpoint specifications applied across all backend providers.