# Filament API Service
[](https://packagist.org/packages/rupadana/filament-api-service) 
## Installation
You can install the package via composer:
```bash
composer require rupadana/filament-api-service
```
Register it to your filament Provider
```php
use Rupadana\ApiService\ApiServicePlugin;
$panel->plugins([
ApiServicePlugin::make()
])
```
### Config
```bash
php artisan vendor:publish --tag=api-service-config
```
```php
return [
'navigation' => [
'token' => [
'cluster' => null,
'group' => 'User',
'sort' => -1,
'icon' => 'heroicon-o-key'
]
],
'models' => [
'token' => [
'enable_policy' => true,
],
],
'route' => [
'panel_prefix' => true,
'use_resource_middlewares' => false,
],
'tenancy' => [
'enabled' => false,
'awareness' => false,
]
];
```
## Usage
```bash
php artisan make:filament-api-service BlogResource
```
Since version 3.0, routes automatically registered. it will grouped as '/api/`admin`'. `admin` is panelId. to disable panelId prefix, please set `route.panel_prefix` to `false`
So, You don't need to register the routes manually.
The routes will be :
| Method | Endpoint | Description |
| ------ | -------------------- | --------------------------- |
| GET | /api/`admin`/blogs | Return LengthAwarePaginator |
| GET | /api/`admin`/blogs/1 | Return single resource |
| PUT | /api/`admin`/blogs/1 | Update resource |
| POST | /api/`admin`/blogs | Create resource |
| DELETE | /api/`admin`/blogs/1 | Delete resource |
On CreateHandler, you need to be create your custom request validation.
### Token Resource
By default, Token resource only show on `super_admin` role. you can modify give permission to other permission too.
Token Resource is protected by TokenPolicy. You can disable it by publishing the config and change this line.
```php
'models' => [
'token' => [
'enable_policy' => false // default: true
]
],
```
> \[!IMPORTANT]\
> If you use Laravel 11, don't forget to run `php artisan install:api` to publish the personal\_access\_tokens migration after that run `php artisan migrate` to migrate the migration, but as default if you run the `php artisan install:api` it will ask you to migrate your migration.
### Filtering & Allowed Field
We used `"spatie/laravel-query-builder": "^5.3"` to handle query selecting, sorting and filtering. Check out [the spatie/laravel-query-builder documentation](https://spatie.be/docs/laravel-query-builder/v5/introduction) for more information. You can specified `allowedFilters` and `allowedFields` in your model. For example:
```php
class User extends Model {
// Which fields can be selected from the database through the query string
public static array $allowedFields = [
'name'
];
// Which fields can be used to sort the results through the query string
public static array $allowedSorts = [
'name',
'created_at'
];
// Which fields can be used to filter the results through the query string
public static array $allowedFilters = [
'name'
];
}
```
### Create a Handler
To create a handler you can use this command. By default, i'm using CreateHandler
```bash
php artisan make:filament-api-handler BlogResource
```
or
```bash
php artisan make:filament-api-handler Blog
```
### Transform API Response
```bash
php artisan make:filament-api-transformer Blog
```
it will be create BlogTransformer in `App\Filament\Resources\BlogResource\Api\Transformers`
```php
resource->toArray();
// or
return md5(json_encode($this->resource->toArray()));
}
}
```
next step you need to edit & add it to your Resource
```php
use App\Filament\Resources\BlogResource\Api\Transformers\BlogTransformer;
class BlogResource extends Resource
{
...
public static function getApiTransformer()
{
return BlogTransformer::class;
}
...
}
```
### Group Name & Prefix
You can edit prefix & group route name as you want, default this plugin use model singular label;
```php
class BlogApiService extends ApiService
{
...
protected static string | null $groupRouteName = 'myblog';
...
}
```
### Middlewares
You can add or override middlewares at two specific places. Via the Filament Panel Provider and/or via the Resources $routeMiddleware.
If you set `route.use_resource_middlewares` to true, the package will register the middlewares for that specific resource as defined in:
```php
class BlogResource extends Resource
{
...
protected static string | array $routeMiddleware = []; // <-- your specific resource middlewares
...
}
```
Then your API resource endpoint will go through these middlewares first.
Another method of adding/overriding middlewares is via the initialization of the plugin in your Panel Provider by adding the `middleware()` method like so:
```php
use Rupadana\ApiService\ApiServicePlugin;
$panel->plugins([
ApiServicePlugin::make()
->middleware([
// ... add your middlewares
])
])
```
### Tenancy
When you want to enable Tenancy on this package you can enable this by setting the config `tenancy.enabled` to `true`. This makes sure that your api responses only retreive the data which that user has access to. So if you have configured 5 tenants and an user has access to 2 tenants. Then, enabling this feature will return only the data of those 2 tenants.
If you have enabled tenancy on this package but on a specific Resource you have defined `protected static bool $isScopedToTenant = false;`, then the API will honour this for that specific resource and will return all records.
If you want to make api routes tenant aware. you can set `tenancy.awareness` to `true` in your published api-service.php. This way this package will register extra API routes which will return only the specific tenant data in the API response.
Now your API endpoints will have URI prefix of `{tenant}` in the API routes when `tenancy.awareness` is `true`.
It will look like this:
```bash
POST api/admin/{tenant}/blog
GET|HEAD api/admin/{tenant}/blog
PUT api/admin/{tenant}/blog/{id}
DELETE api/admin/{tenant}/blog/{id}
GET|HEAD api/admin/{tenant}/blog/{id}
```
Overriding tenancy ownership relationship name by adding this property to the Handlers `protected static ?string $tenantOwnershipRelationshipName = null;`
### How to secure it?
Since version 3.0, it will automatically detect routes and secure it using sanctum.
To Generate Token, you just need create it from admin panel. It will be Token Resource there.
### Public API
Set API to public by overriding this property on your API Handler. Assume we have a `PaginationHandler`
```php
class PaginationHandler extends Handlers {
public static bool $public = true;
}
```
## License
The MIT License (MIT).
## Supported By
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.codecrafters.id/plugins/filament-api-service.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
