SDK Sync ve Async

SDK ile CRUD, RPC ve sayfalama

English · Türkçe · Languages / Diller

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

Senkron CRUD

import os
from json_api_forge import ForgeClient

with ForgeClient("https://api.example.com", api_key=os.environ["FORGE_API_KEY"]) as forge:
    created = forge.create_item("wiki-demo", "items", {"name": "SDK kaydı"})
    print(created.status_code, created.data, created.request_id)
    page = forge.list_items("wiki-demo", "items", params={"limit": 20, "sort": "id"})
    item_id = str(page.data["items"][0]["id"])
    forge.get_item("wiki-demo", "items", item_id)
    forge.update_item("wiki-demo", "items", item_id, {"name": "Değişti"})
    forge.delete_item("wiki-demo", "items", item_id)

replace=True, update_item için PUT seçer; varsayılan PATCH'tir. ID argümanını string'e dönüştürün. Response, ham dict yerine ForgeResponse nesnesidir. data sunucunun JSON'unu olduğu gibi temsil eder; her endpointin items döndürdüğünü varsaymayın.

Asenkron kullanım

import asyncio
import os
from json_api_forge import AsyncForgeClient

async def main():
    async with AsyncForgeClient(
        "https://api.example.com", api_key=os.environ["FORGE_API_KEY"]
    ) as forge:
        result = await forge.list_items("wiki-demo", "items", params={"limit": 20})
        print(result.data)

if __name__ == "__main__":
    asyncio.run(main())

Zaten çalışan event loop içinde (örneğin async web uygulaması) asyncio.run başlatmak yerine coroutine'i await edin. Senkron istemcinin bekleme yapan çağrılarını doğrudan event loop'a koymayın.

Operation çağırma

result = forge.call_operation(
    "wiki-demo", "items.rename", {"id": 1, "name": "Yeni ad"},
    idempotency_key="rename-command-001",
)

Bu helper POST /api/<project>/v1/rpc/<operation> üretir. Operation'ın özel path'i veya GET method'u varsa:

result = forge.request(
    "GET", "api/guild-ledger/v1/rpc/ledger.balance/member-123"
)

operation.name, her zaman çağrılacak bütün URL değildir. call_operation adıyla sunucudaki bütün operation türlerini keşfetmez.

Offset iterator

for item in forge.iter_items("wiki-demo", "items", page_size=50, max_items=500):
    print(item)

Bu yardımcının v0.5.1'de yalnız ForgeClient üzerinde bulunduğunu unutmayın. AsyncForgeClient'ta aynı adlı async iterator yoktur. Helper offset'i 0'dan başlatır; params içindeki offset ile kaldığı yerden devam özelliği olarak kullanılmaz. Server'ın max_limit değerini aşmayan page_size seçin; server daha az limit uygularsa iterator kısa sayfayı son sayfa kabul edebilir.

Async kaynakta kendi bounded offset döngünüzü yazın. Cursor kaynağında ise next_cursor izleyin:

async def read_cursor_pages(forge):
    cursor = None
    for _ in range(100):
        params = {"limit": 50}
        if cursor is not None:
            params["cursor"] = cursor
        response = await forge.list_items("notes", "notes", params=params)
        for item in response.data["items"]:
            yield item
        cursor = response.data.get("next_cursor")
        if not response.data.get("has_more") or cursor is None:
            break

Bu örnek server tarafında cursor olarak yapılandırılmış notes kaynağını varsayar. Aynı cursor'ın tekrar etmesini, silinen kayıtları veya pagination sırasında yeni veri gelmesini uygulamanızın tutarlılık gereksinimine göre ele alın.

request JSON, multipart files, params, headers ve expect_json=False ile binary/text yanıtları destekler. JSON gövdesi ve files birlikte gönderilmez. SSE/WebSocket için bu buffered HTTP yanıt API'sini sınırsız streaming client gibi kullanmayın.

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.

• python-library/json_api_forge/client.py
• python-library/json_api_forge/models.py

---

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