citrus-cms/resources/views/guide/dynamic-api-and-scribe-guide.md

# Dynamic Resource API Usage Guide / Dinamik Kaynak API Kullanım Kılavuzu

This guide details how to use the Dynamic Resource API endpoint (`/api/{table}/{action}`) and explains each parameter in depth.
Bu kılavuz, Dinamik Kaynak API uç noktasının (`/api/{table}/{action}`) nasıl kullanılacağını ve her bir parametrenin ne işe yaradığını detaylandırır.

---

## 1. Endpoint Structure / Uç Nokta Yapısı

**URL:** `POST /api/{table}/{action}`  
(Also supports GET for read operations, but POST is recommended for complex filters)
(Okuma işlemleri için GET de desteklenir ancak karmaşık filtreler için POST önerilir)

### Path Parameters / Yol Parametreleri

#### 1. `{table}`
This parameter defines the target resource. It can be one of two things:
Bu parametre hedef kaynağı tanımlar. İki şeyden biri olabilir:

*   **Module Slug (Recommended / Önerilen):** e.g., `test-packages`, `weld-log`, `radiographic-test`.
    *   **How it works:** The system looks up this slug in the `types` table.
    *   **Security:** Checks module-based permissions (`isAuth`).
    *   **Result:** Resolves to the actual database table defined in the module settings (e.g., `test-packages` -> `test_packages`).
    *   **Nasıl çalışır:** Sistem bu kısa adı `types` tablosunda arar.
    *   **Güvenlik:** Modül bazlı izinleri kontrol eder.
    *   **Sonuç:** Modül ayarlarında tanımlı gerçek veritabanı tablosuna yönlenir.

*   **Table Name (Direct / Direkt):** e.g., `users`, `logs`.
    *   **How it works:** Accesses the database table directly.
    *   **Security:** Requires standard API authentication (Bearer Token). Bypasses module permissions.
    *   **Nasıl çalışır:** Veritabanı tablosuna doğrudan erişir.
    *   **Güvenlik:** Standart API kimlik doğrulaması gerektirir. Modül izinlerini atlar.

#### 2. `{action}`
Defines the operation to perform.
Gerçekleştirilecek işlemi tanımlar.

| Action | HTTP Method Equivalent | Permission Required (Module) | Description / Açıklama |
| :--- | :--- | :--- | :--- |
| `read`, `list`, `get` | GET | **read** | Fetch records. (Kayıtları getir) |
| `create`, `store`, `insert` | POST | **write** | Create a new record. (Yeni kayıt oluştur) |
| `update`, `save` | PUT/PATCH | **write** | Update an existing record. (Kayıt güncelle) |
| `delete`, `remove` | DELETE | **full_control** | Delete a record. (Kayıt sil) |
| `view`, `render` | GET | **read** | Render a server-side Blade view. (Blade şablonu render et) |

---

## 2. Body Parameters / Gövde Parametreleri

These parameters are sent in the JSON body of the request.
Bu parametreler isteğin JSON gövdesinde gönderilir.

### `filter` (Array/JSON)
Used for filtering data. Supports **DevExtreme** filter syntax.
Veriyi filtrelemek için kullanılır. **DevExtreme** filtre sözdizimini destekler.

*   **Simple Filter:** `["field", "operator", "value"]`
*   **Complex Filter:** `[["field1", "=", "value1"], "and", ["field2", ">", 10]]`
*   **Operators:** `=`, `<>`, `>`, `>=`, `<`, `<=`, `contains`, `notcontains`, `startswith`, `endswith`.

**Example / Örnek:**
```json
"filter": [
    ["status", "=", "active"],
    "and",
    ["created_at", ">", "2023-01-01"]
]
```

### `sort` (Array/JSON)
Defines sorting order.
Sıralama düzenini belirler.

**Example / Örnek:**
```json
"sort": [
    { "selector": "created_at", "desc": true },
    { "selector": "name", "desc": false }
]
```

### `skip` (Integer) & `take` (Integer)
Used for pagination.
Sayfalama için kullanılır.

*   `skip`: How many records to skip (offset). (Kaç kayıt atlanacak)
*   `take`: How many records to return (limit). (Kaç kayıt getirilecek)

### `columns` (Array/String)
Used to retrieve specific columns. If omitted or null, returns all columns (`*`).
Belirli sütunları getirmek için kullanılır. Atlanırsa veya null ise tüm sütunları (`*`) döndürür.

*   **Format:** JSON Array of strings or Comma-separated string.
*   **Format:** JSON String dizisi veya virgülle ayrılmış string.

**Example / Örnek:**
```json
"columns": ["id", "title", "status"]
```
**Or / Veya:**
```json
"columns": "id, title, status"
```

### `data` (Object)
**Required for:** `create`, `update`.
Contains the fields and values to be saved.
Kaydedilecek alanları ve değerleri içerir.

**Note:** The system automatically filters out fields that do not exist in the database table to prevent errors.
**Not:** Sistem, veritabanı tablosunda olmayan alanları hataları önlemek için otomatik olarak filtreler.

**Example / Örnek:**
```json
"data": {
    "name": "Project X",
    "status": "pending",
    "budget": 5000
}
```

### `id` or `key` (Integer/String)
**Required for:** `update`, `delete`.
Identifier of the record to update or delete.
Güncellenecek veya silinecek kaydın kimliği.

### `file` (String)
**Required for:** `view`.
The name of the Blade file to render (without `.blade.php`).
Render edilecek Blade dosyasının adı (`.blade.php` olmadan).

*   **Search Path 1:** `resources/views/admin/{table}/{file}.blade.php`
*   **Search Path 2:** `resources/views/admin/type/{table}/{file}.blade.php`

---

## 3. Example Scenarios / Örnek Senaryolar

### Scenario 1: Fetch Data with Filtering (Veri Çekme ve Filtreleme)
**Request:** `POST /api/weld-log/read`
```json
{
    "filter": [["weld_no", "contains", "W-10"]],
    "sort": [{"selector": "id", "desc": true}],
    "take": 10
}
```

### Scenario 2: Update a Record (Kayıt Güncelleme)
**Request:** `POST /api/users/update`
```json
{
    "id": 15,
    "data": {
        "email": "new@example.com",
        "status": "active"
    }
}
```

### Scenario 3: Render a Form View (Form Görünümü Render Etme)
**Request:** `POST /api/test-packages/view`
```json
{
    "file": "form",
    "id": 5
}
```
*   **Looks for:** `admin.type.test_packages.form` or `admin.test_packages.form` view.
*   **Returns:** HTML content of the form.