Filament Api Service

Enable tenant-aware API responses to ensure users only retrieve data belonging to their authorized tenants.

• Enable Tenancy: Set tenancy.enabled to true in the config. This automatically scopes queries to the user's tenants.
• Tenant Awareness (URI Prefix): Set tenancy.awareness to true. This adds a {tenant} prefix to your API routes (e.g., api/admin/{tenant}/blog).
• Override Scoping: In a specific Resource, set protected static bool $isScopedToTenant = false; to return all records regardless of tenancy.
• Custom Relationship: In a Handler, override protected static ?string $tenantOwnershipRelationshipName = null; to change the relationship used for scoping.

// Example of tenant-aware route structure when awareness is enabled:
// POST api/admin/{tenant}/blog
// GET  api/admin/{tenant}/blog/{id}

Use the Artisan command to automatically generate RESTful API endpoints for an existing Filament resource. By default, routes are prefixed with your panel ID (e.g., /api/admin/blogs).

Available endpoints generated:

• GET /api/{panel_id}/{resource}: Returns a LengthAwarePaginator.
• GET /api/{panel_id}/{resource}/{id}: Returns a single resource.
• PUT /api/{panel_id}/{resource}/{id}: Updates a resource.
• POST /api/{panel_id}/{resource}: Creates a resource.
• DELETE /api/{panel_id}/{resource}/{id}: Deletes a resource.

php artisan make:filament-api-service BlogResource

The package provides built-in authentication routes:

• POST /api/auth/login
• POST /api/auth/logout

It integrates with spatie/laravel-permission and filament-shield. By default, it uses the permission middleware. If you wish to use a different middleware setup, set use-spatie-permission-middleware to false in the config.

To use Filament Api Service, install it via Composer and register the plugin in your Filament Panel Provider.

Note for Laravel 11 users: You must run php artisan install:api to publish the personal_access_tokens migration, then run php artisan migrate.

# Install the package
composer require rupadana/filament-api-service

// Register in your Filament Provider
use Rupadana\
ApiService\[ApiServicePlugin\;

$panel->plugins([
    ApiServicePlugin::make()
]);

Handlers manage the logic for specific API actions. You can generate specific handlers (Create, Update, Delete, Detail, Pagination) using the Artisan command.

To customize the logic of a generated handler, you can export the stubs to your application and edit them directly.

# Generate a handler for a resource
php artisan make:filament-api-handler BlogResource

# Export handler stubs for customization
php artisan vendor:publish --tag=api-service-stubs

While the package supports auto-discovery of API services in clusters (since v4.0.1), creating new services for clustered resources requires manual directory structure setup.

If your resource is at App\Filament\Clusters\Catalog\Resources\ProductResource, you must manually create the following structure:

app/Filament/Clusters/Catalog/Resources/
└── Products/
    ├── ProductResource.php
    ├── Api/
    │   ├── ProductApiService.php
    │   ├── Transformers/
    │   │   └── ProductTransformer.php
    │   └── Handlers/
    │       ├── CreateHandler.php
    │       ├── UpdateHandler.php
    │       ├── DeleteHandler.php
    │       ├── DetailHandler.php
    │       └── PaginationHandler.php

Tip: The easiest way to implement this is to copy the structure from tests/Fixtures/Resources/Product/Api/ and adapt the namespaces.

Scramble may not automatically detect filter/sort options or custom transformer structures.

To document filters and sorts manually, add PHPDoc annotations to your handlers:

/**
 * Get paginated list of products
 * 
 * @queryParam filter[name] Filter by product name
 * @queryParam sort Sort by field (e.g., name, created_at)
 * @queryParam fields[products] Select specific fields (e.g., id,name,price)
 */
public function handler(): JsonResponse
{
    // ...
}

/**
 * Get paginated list of products
 * 
 * @queryParam filter[name] Filter by product name
 * @queryParam sort Sort by field (e.g., name, created_at)
 * @queryParam fields[products] Select specific fields (e.g., id,name,price)
 */
public function handler(): JsonResponse
{
    // Your handler logic
}

The package uses Spatie's permission middleware by default. If you receive "User does not have the right permissions" errors:

1. Setup Shield: Run php artisan shield:setup --fresh and php artisan shield:install.
2. Generate Permissions: Run php artisan shield:generate --all to create permissions for your API handlers (e.g., view_blog, create_blog).
3. Assign Roles: Use the Filament Shield UI to assign these new permissions to your roles.

To disable permission middleware entirely, update config/api-service.php:

return [
    'use-spatie-permission-middleware' => false,
];

To customize the JSON structure returned by your API, use Transformers.

1. Generate a transformer using php artisan make:filament-api-transformer {Resource}.
2. Implement the toArray($request) method in the generated class.
3. Register the transformer in your Filament Resource by overriding getApiTransformer().

// 1. Generate
// php artisan make:filament-api-transformer Blog

// 2. Implement (App\Filament\Resources\BlogResource\Api\Transformers\BlogTransformer)
class BlogTransformer extends JsonResource
{
    public function toArray($request)
    {
        return $this->resource->toArray();
    }
}

// 3. Register in your Resource
class BlogResource extends Resource
{
    public static function getApiTransformer()
    {
        return BlogTransformer::class;
    }
}

If desktop applications are being redirected to login instead of accessing the API, check the following:

1. Middleware: Ensure routes use auth:sanctum (the package default). Verify in config/api-service.php:

   'logout-middleware' => ['auth:sanctum'],

2. CORS: If the app is on a different domain, update config/cors.php:

   'paths' => ['api/*', 'sanctum/csrf-cookie'],
   'allowed_origins' => ['*'], // Or your specific domain
   'supports_credentials' => true,

3. Authentication: Desktop apps must use token-based authentication by sending the header: Authorization: Bearer {your-token}
4. Session: Ensure you are not using session-based authentication for API routes; use Sanctum tokens.