API'ye genel bakış

Public API, hesaplayıcıları sunucu tarafında çalıştıran açık bir JSON API’sidir. Kimlik doğrulama yoktur, API anahtarı gerekmez ve uçlar tarayıcıdan doğrudan çağrılabilir.


Temel adres	`https://api.mirac-ozdemir.com`
Public uçlar	`https://api.mirac-ozdemir.com/v1/public/…`
Biçim	JSON, UTF-8 (`Content-Type: application/json`)
Kimlik doğrulama	Yok
Makine okunur sözleşme	`/openapi.json` (OpenAPI 3.1)
Durum	api.mirac-ozdemir.com

Uçlar

İşlem	Uç	Ne yapar
`listTools`	`GET /v1/public/tools`	Yayındaki araçları sayfalı listeler.
`searchTools`	`GET /v1/public/search`	Araçlarda arama yapar.
`listCategories`	`GET /v1/public/categories`	Kategori ağacını döner.
`getToolByKey`	`GET /v1/public/tools/by-key/{key}`	Araç tanımını `key` ile getirir.
`calculateByKey`	`POST /v1/public/tools/by-key/{key}/calculate`	Hesaplar (önerilen uç).
`getToolBySlug`	`GET /v1/public/tools/by-slug/{locale}/{slug}`	Web sitesi adresinden aracı çözümler.
`calculateTool`	`POST /v1/public/tools/{toolId}/calculate`	`toolId` ile hesaplar.

Her ucun parametreleri ve yanıt şemaları API Referansı’nda, otomatik olarak sözleşmeden üretilmiş halde bulunur.

Sürümleme

Yol, API sürümünü içerir (/v1). Geriye dönük uyumlu değişiklikler (yeni alanlar, yeni isteğe bağlı parametreler) aynı sürümde yapılır; istemcileriniz bilmediği alanları yok saymalıdır. Kırıcı değişiklikler yeni bir sürümle (/v2) yayınlanır. API sürümü, araçların kendi sürümlerinden (versionNumber) bağımsızdır.

Yanıt zarfları

Başarılı yanıtlar data (ve gerekiyorsa meta) içerir; hatalar error içerir:

{ "data": { … }, "meta": { … } }
{ "data": [ … ], "meta": { "page": 1, "pageSize": 20, "total": 100, "totalPages": 5 } }
{ "error": { "code": "VALIDATION_ERROR", "message": "…", "details": { … } }, "requestId": "…" }

Liste uçları sayfalıdır: page (≥ 1) ve pageSize (1–100; arama için en çok 50). Hata kodlarının tamamı için Hatalar sayfasına bakın.

İstek kimliği

Her yanıt X-Request-Id başlığını taşır; hata gövdelerinde ayrıca requestId bulunur. Kendi kimliğinizi X-Request-Id başlığıyla gönderebilirsiniz ([A-Za-z0-9._:-], 8–128 karakter); geçersizse sunucu yenisini üretir. Destek taleplerinde bu değeri iletin.

CORS

Public uçlar tüm origin’lere açıktır:

Access-Control-Allow-Origin: *; çerez veya kimlik bilgisi kullanılmaz.
İzin verilen yöntemler GET, POST, OPTIONS; izin verilen istek başlıkları Content-Type ve X-Request-Id.
Okunabilen yanıt başlıkları: X-Request-Id, Retry-After, RateLimit-Limit, RateLimit-Remaining.
Preflight yanıtları 24 saat önbelleğe alınır.

Bu yüzden tarayıcıdaki uygulamanızdan, bir proxy kurmadan doğrudan çağrı yapabilirsiniz.

Önbellek

Okuma uçları (GET) önbelleklenebilir yanıtlar verir:

Cache-Control: public, max-age=5, s-maxage=30, stale-while-revalidate=300

Hesaplama yanıtları Cache-Control: no-store ile döner. Araç tanımlarını ve kategori ağacını kendi tarafınızda da önbelleğe alın; hesaplama öncesinde her seferinde yeniden okumanıza gerek yoktur. Tanım değiştiğinde version kontrolü size haber verir (Hesaplama).

Sınırlar

Adil kullanım için IP başına sınırlar vardır (hesaplama ve arama için dakikada 60 istek), gövde 16 KB’ı aşamaz ve istekler 15 saniyede zaman aşımına uğrar. Ayrıntılar: Hız sınırları.

Araç keşfiListeleme, arama ve kategoriler.

Araç tanımıGirdi, çıktı ve arayüz şemaları.