Ilk API

İlk API: oluşturma, anahtar, CRUD ve RPC

English · Türkçe · Languages / Diller

Kapsam: JSON API Forge 0.5.1 · İnceleme: 17 Eylül 2026 · Dil: Türkçe

Bu örnek boş bir dağıtım dizininde çalışır. Sunucu paketi kurulu ve forge erişilebilir olmalıdır. Mevcut canlı projede deneme anahtarları üretmeyin.

1. Uygulamayı oluşturun

forge new WikiDemo --slug wiki-demo --preset postgres-api
forge init
forge validate
forge doctor
forge routes
forge dev

WikiDemo klasör adıdır, wiki-demo API slug'ıdır. postgres-api, başlangıç için items kaynağını üretir; ayrıca URL ayarlanmadıkça SQLite kullanır. data/ altında dosya oluşur. Proje URL'si /api/wiki-demo/v1 olur.

forge init, WIKI_DEMO_BOOTSTRAP_ADMIN_KEY değişkenini özel .env dosyasında üretir. Dosya zaten varsa komut durur. Yeni proje eklemek için --force kullanmak mevcut yönetilen sırları da döndürür; CLI açıklamasını okuyun.

2. Kalıcı yönetici anahtarı oluşturun

Sunucu çalışırken ikinci terminalde aşağıdaki Python kodunu çalıştırın. httpx sunucu bağımlılığıdır. getpass anahtarları ekranda göstermez. Oluşan ham API anahtarı yalnızca oluşturma yanıtında döner; bu örnekte bellekte tutulur.

from getpass import getpass
import httpx

base = "http://127.0.0.1:8000/api/wiki-demo/v1"
bootstrap = getpass(".env içindeki WIKI_DEMO_BOOTSTRAP_ADMIN_KEY: ")

with httpx.Client(timeout=10, trust_env=False) as http:
    response = http.post(
        f"{base}/admin/api-keys",
        headers={"X-API-Key": bootstrap},
        json={"name": "wiki-admin", "roles": ["admin"]},
    )
    response.raise_for_status()
    admin_key = response.json()["api_key"]

    # Bootstrap ilk başarılı anahtar üretiminden sonra tüketilir.
    response = http.post(
        f"{base}/admin/api-keys",
        headers={"X-API-Key": admin_key},
        json={
            "name": "wiki-demo-client",
            "permissions": [
                "wiki-demo.items.list", "wiki-demo.items.read",
                "wiki-demo.items.create", "wiki-demo.items.update",
                "wiki-demo.items.delete", "system.meta.read",
            ],
        },
    )
    response.raise_for_status()
    app_key = response.json()["api_key"]
    headers = {"X-API-Key": app_key}

    created = http.post(f"{base}/items", headers=headers, json={"name": "İlk kayıt"})
    created.raise_for_status()
    print("Oluşturulan kayıt:", created.json())

    listed = http.get(f"{base}/items", headers=headers, params={"limit": 10, "sort": "id"})
    listed.raise_for_status()
    item_id = listed.json()["items"][0]["id"]

    updated = http.patch(f"{base}/items/{item_id}", headers=headers, json={"name": "Güncellendi"})
    updated.raise_for_status()
    deleted = http.delete(f"{base}/items/{item_id}", headers=headers)
    deleted.raise_for_status()

Bu öğretici disposable kurulum içindir. Normal kullanımda yönetici anahtarını güvenli bir sır deposuna kaydedin ve sıradan istemcilere kapsamlı olmayan uygulama anahtarı verin. Scripti ikinci kez aynı bootstrap anahtarıyla çalıştırmak beklenen biçimde başarısız olur; veri silerek bootstrap'ı yeniden açmayın.

3. Projenizi inceleyin

Dosya	İçeriği
app/WikiDemo/app.json	İsim, slug, API prefix ve uygulama sürümü
config/10-databases.json	primary bağlantısı ve env başvurusu
config/20-security.json	Bootstrap ve admin rolü
config/30-performance.json	Bellek cache ve rate limit
config/40-resources.json	items tablosu ve alan/izin kuralları

4. Bir RPC ekleyin

app/WikiDemo/config/70-operations.json oluşturun:

{
  "operations": [
    {
      "name": "items.rename",
      "permission": "wiki-demo.items.update",
      "transaction": true,
      "idempotency": true,
      "input_schema": {
        "type": "object",
        "required": ["id", "name"],
        "additionalProperties": false,
        "properties": {
          "id": {"type": "integer", "minimum": 1},
          "name": {"type": "string", "minLength": 1, "maxLength": 120}
        }
      },
      "statements": [
        {
          "sql": "UPDATE items SET name = :name WHERE id = :id",
          "params": {"id": "$body.id", "name": "$body.name"},
          "mode": "execute",
          "require_rowcount_min": 1,
          "require_rowcount_max": 1,
          "result_name": "updated"
        }
      ],
      "invalidate_resources": ["items"]
    }
  ]
}

forge validate çalıştırın. Yeni kayıt oluşturup POST /api/wiki-demo/v1/rpc/items.rename adresine {"id":1,"name":"RPC ile"} gövdesini ve Idempotency-Key: rename-001 başlığını gönderin; 1 yerine gerçek kayıt ID'sini kullanın. Aynı anahtar ve gövde ilk sonucu tekrar oynatır. Aynı anahtarla farklı gövde 409 üretir. JSON reload kapalıysa sunucuyu kontrollü yeniden başlatın.

Bu örnek kullanıcıdan SQL metni almaz. Çok kiracılı bir projeye taşırken SQL WHERE koşullarına server tarafından alınan tenant/sahiplik bağlamını eklemek ayrıca sizin sorumluluğunuzdur.

Kaynak ve doğrulama

Bu sayfa aşağıdaki sabit commitlerdeki davranışı açıklar. Yeni bir sürümde aynı davranışın sürdüğünü varsaymayın.

• main/framework/cli.py
• main/framework/api_models.py
• main/framework/routers/project.py
• main/framework/security.py
• main/framework/operations.py

---

Wiki ana sayfa · Tüm sayfalar · Sürüm ve bakım