---
url: https://record-api-docs.vercel.app/guide/usage.md
---

# Usage

## Usage Examples

Once installed, you can immediately start using the dynamic API endpoints:

```bash
# List users with pagination
GET /api/users

# Get specific user with relationships
GET /api/users/1?select=*,posts(*),roles(*)

# Create new user
POST /api/users
{
    "name": "John Doe",
    "email": "john@example.com"
}

# Update user
PUT /api/users/1
{
    "name": "Jane Doe"
}

# Delete user (soft delete)
DELETE /api/users/1

# Search users
GET /api/users?s=john&status=eq.active

# Advanced filtering
GET /api/users?age=gt.18&created_at=between.2024-01-01,2024-12-31
```

## API Endpoints

The package automatically registers RESTful API routes for dynamic database operations. The route prefix is configurable via `config('record.api_prefix')` (default: `api/v1`).

### Route Configuration

```php
// config/record.php
'api_prefix' => 'api/v1',
```

**Examples:**

* `'api'` → `/api/{table}`
* `'api/v1'` → `/api/v1/{table}`
* `'api/v2'` → `/api/v2/{table}`
* `'records'` → `/records/{table}`

### Standard CRUD Operations

* `GET /{prefix}/{table}` - List records with filtering and pagination
* `GET /{prefix}/{table}/{id}` - Get specific record
* `POST /{prefix}/{table}` - Create new record
* `PUT/PATCH /{prefix}/{table}/{id}` - Update record
* `POST /{prefix}/{table}/upsert` - Upsert (create or update) record
* `DELETE /{prefix}/{table}/{id}` - Soft delete record

### Advanced Operations

* `POST /{prefix}/{table}/{id}/restore` - Restore soft-deleted record
* `DELETE /{prefix}/{table}/{id}/force` - Permanently delete record
* `POST /{prefix}/{table}/bulk` - Bulk operations
* `POST /{prefix}/{table}/bulk/create` - Bulk create
* `POST /{prefix}/{table}/bulk/update` - Bulk update
* `POST /{prefix}/{table}/bulk/delete` - Bulk delete
* `POST /{prefix}/{table}/bulk/upsert` - Bulk upsert

### RPC Functions

* `GET|POST|PUT|PATCH|DELETE /{prefix}/rpc/{functionName}` - Execute global functions
* `GET|POST|PUT|PATCH|DELETE /{prefix}/{table}/rpc/{functionName}` - Execute table-specific functions

## Usage

* Middleware:
  * Add `request.id` to routes or groups: `Route::middleware(['request.id'])->group(function () { ... });`.
* Responses:
  * Resolve via container: `$service = app('api.response');`
  * `return $service->success(['items' => []]);`
  * All responses include `meta.request_id` when middleware is active.

## Example Controller

```php
use Illuminate\Http\Request;

class ExampleController
{
    public function index(Request $request)
    {
        $responses = app('api.response');
        return $responses->success(['message' => 'OK']);
    }
}
```

## QueryHelpers Trait

The `QueryHelpers` trait provides powerful query filtering and manipulation capabilities for Eloquent models.

### Usage

```php
use Mylekha\RecordApi\Traits\QueryHelpers;

class YourModel extends Model
{
    use QueryHelpers;
}
```

### Available Methods

* `applyRequestFilters($request, $isArray = false, $orderBy = 'id')` - Apply request-based filters

### Supported Query Parameters

* `s` - Search all fields (e.g., `?s=cambodia`)
* `select` - Specify columns including relationships (e.g., `?select=id,name,customer:id,name`)
* `with` - Load related models (e.g., `?with=user,posts.comments`)
* `sortby` - Column to sort by (e.g., `?sortby=name`)
* `order` - Sort direction: asc/desc (e.g., `?order=asc`)
* `per_page` - Enable pagination (e.g., `?per_page=20`)
* `limit` - Limit results when isArray=true (e.g., `?limit=1000`)
* `lazy` - Enable lazy loading (e.g., `?lazy=true`)

### Filter Operators

Supported syntax includes:

* Standard filters: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `between`, `not_between`, `like`, `ilike`, `contains`, `starts_with`, `ends_with`, `regex`, `match`, `imatch`, date operators, and null/empty operators.
* Grouped logic: `and=(...)`, `or=(...)`.
* Advanced expression style: `not.<operator>` and `operator(any|all).{...}`.
* List styles: both `id=in.(5,6,9)` and legacy `id=in.5,6,9`.
* Driver guard: unsupported operators return `422` validation error with explicit message.

For complete operator matrix, grouped logic examples, and driver compatibility details, see:

* `docs/api-documentation.md` → **Filter Operators** and **Grouped Logic**.

### Example Usage

```php
// In your controller
public function index(Request $request)
{
    $results = YourModel::query()
        ->applyRequestFilters($request, true);
    
    return response()->json($results);
}
```

You can also use named arguments when calling the scope (PHP 8+):

```php
$results = YourModel::query()->applyRequestFilters(
    request: $request,
    isArray: true,
    orderBy: 'created_at',
);
```