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:

"filter": [
    ["status", "=", "active"],
    "and",
    ["created_at", ">", "2023-01-01"]
]

sort (Array/JSON)

Defines sorting order. Sıralama düzenini belirler.

Example / Örnek:

"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:

"columns": ["id", "title", "status"]

Or / Veya:

"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:

"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

{
    "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

{
    "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

{
    "file": "form",
    "id": 5
}

• Looks for: admin.type.test_packages.form or admin.test_packages.form view.
• Returns: HTML content of the form.