Yanıt Formatları

API Yanıt Yapılarını Anlama

mindzieAPI yanıt formatları, durum kodları, hata yönetimi desenleri ve veri yapıları hakkında bilgi edinerek sağlam entegrasyonlar oluşturun.

Standart Yanıt Formatı

Tüm mindzieAPI yanıtları, öngörülebilir yapılarla tutarlı JSON formatlamayı takip eder:

Başarılı Yanıt

{
  "data": {
    // Birincil yanıt verisi
  },
  "metadata": {
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_12345",
    "version": "1.0.0"
  },
  "pagination": {
    // Sayfalandırılmış yanıtlar için mevcut
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 100,
    "itemsPerPage": 20,
    "hasNext": true,
    "hasPrevious": false
  }
}

Hata Yanıtı

{
  "error": {
    "code": "validation_failed",
    "message": "İstek doğrulaması başarısız oldu",
    "details": {
      "field": "datasetId",
      "reason": "Geçersiz GUID formatı"
    },
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_12345"
  }
}

Yanıt Türleri

Başarılı Yanıtlar

Yapılandırılmış JSON veri ve metadata içeren HTTP 2xx durum kodları.

Hata Yanıtları

Detaylı hata bilgileri içeren HTTP 4xx/5xx durum kodları.

Sayfalandırma

Büyük veri seti yanıtlarında tutarlı sayfalandırma formatı.

HTTP Durum Kodları

Başarı Kodları (2xx)

Kod	Durum	Açıklama	Kullanım
200	OK	İstek başarılı, veri döndürüldü	GET istekleri, başarılı işlemler
201	Created	Kaynak başarıyla oluşturuldu	Yeni kaynak oluşturan POST istekleri
202	Accepted	İstek asenkron işlemler için kabul edildi	Uzun süren işlemler, kuyruğa alınan görevler
204	No Content	İstek başarılı, veri döndürülmedi	DELETE istekleri, veri döndürmeyen güncellemeler

İstemci Hatası Kodları (4xx)

Kod	Durum	Açıklama	Yaygın Sebepler
400	Bad Request	Geçersiz istek formatı veya parametreler	Eksik başlıklar, hatalı JSON, biçimsiz veri
401	Unauthorized	Kimlik doğrulama gerekli veya başarısız	Eksik/geçersiz token, süresi dolmuş kimlik bilgileri
403	Forbidden	Geçerli kimlik doğrulama ancak yetersiz izinler	Kısıtlı kullanıcı erişimi, yanlış tenant/proje
404	Not Found	İstenen kaynak mevcut değil	Geçersiz uç nokta, var olmayan kaynak ID'si
422	Unprocessable Entity	Geçerli format ancak iş mantığı doğrulaması başarısız	Geçersiz iş kuralları, kısıtlama ihlalleri
429	Too Many Requests	Kota sınırı aşıldı	Belirli zaman içinde çok fazla API çağrısı

Sunucu Hatası Kodları (5xx)

Kod	Durum	Açıklama	Eylem
500	Internal Server Error	Beklenmeyen sunucu hatası	Üssel geri çekilmeyle yeniden dene
502	Bad Gateway	Yukarı akış servis hatası	Servis durumunu kontrol et, sonra yeniden dene
503	Service Unavailable	Servis geçici olarak kullanılamıyor	Gecikmeli yeniden dene, bakım kontrolü yap
504	Gateway Timeout	İstek zaman aşımına uğradı	Zaman aşımını artır, isteği optimize et

Yaygın Yanıt Desenleri

Tek Kaynak Yanıtı

{
  "actionId": "87654321-4321-4321-4321-210987654321",
  "actionType": "analyze",
  "status": "completed",
  "startTime": "2024-01-15T10:30:00Z",
  "endTime": "2024-01-15T10:32:15Z",
  "duration": 135,
  "result": {
    "outputId": "98765432-8765-4321-4321-987654321098",
    "recordsProcessed": 10000
  }
}

Sayfalandırma ile Koleksiyon Yanıtı

{
  "actions": [
    {
      "actionId": "87654321-4321-4321-4321-210987654321",
      "actionType": "analyze",
      "status": "completed"
    },
    {
      "actionId": "11111111-2222-3333-4444-555555555555",
      "actionType": "export",
      "status": "processing"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 100,
    "itemsPerPage": 20,
    "hasNext": true,
    "hasPrevious": false,
    "links": {
      "first": "/api/Action/history?page=1&limit=20",
      "next": "/api/Action/history?page=2&limit=20",
      "last": "/api/Action/history?page=5&limit=20"
    }
  }
}

Asenkron İşlem Yanıtı

{
  "operationId": "op_12345678-1234-1234-1234-123456789012",
  "status": "processing",
  "progress": {
    "percentage": 45,
    "currentStep": "data_analysis",
    "totalSteps": 5,
    "estimatedCompletion": "2024-01-15T10:35:00Z"
  },
  "trackingUrl": "/api/Execution/status/op_12345678-1234-1234-1234-123456789012",
  "message": "Veri seti analizi işleniyor..."
}

Hata Yanıtı Detayları

Doğrulama Hatası

{
  "error": {
    "code": "validation_failed",
    "message": "İstek doğrulaması başarısız oldu",
    "details": {
      "errors": [
        {
          "field": "datasetId",
          "code": "invalid_format",
          "message": "Geçerli bir GUID olmalıdır"
        },
        {
          "field": "parameters.timeout",
          "code": "out_of_range",
          "message": "1 ile 3600 saniye arasında olmalıdır"
        }
      ]
    },
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_12345"
  }
}

Kimlik Doğrulama Hatası

{
  "error": {
    "code": "invalid_token",
    "message": "Sağlanan erişim tokenı geçersiz veya süresi dolmuş",
    "details": {
      "tokenType": "bearer",
      "expiresAt": "2024-01-15T09:00:00Z",
      "suggestion": "Lütfen erişim tokenınızı yenileyin"
    },
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_12345"
  }
}

Kota Aşımı Hatası

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Bu uç nokta için kota sınırı aşıldı",
    "details": {
      "limit": 100,
      "remaining": 0,
      "resetTime": "2024-01-15T11:00:00Z",
      "retryAfter": 1800
    },
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_12345"
  }
}

Yanıt Başlıkları

Standart Başlıklar

Başlık	Açıklama	Örnek
Content-Type	Yanıt formatı	application/json; charset=utf-8
X-Request-Id	Benzersiz istek tanımlayıcısı	req_12345678
X-Response-Time	Sunucu işleme süresi	145ms
X-API-Version	Kullanılan API sürümü	1.0.0

Kota Sınırlandırma Başlıkları

Başlık	Açıklama	Örnek
X-RateLimit-Limit	Pencere başına maksimum istek sayısı	100
X-RateLimit-Remaining	Pencere içinde kalan istekler	95
X-RateLimit-Reset	Pencere sıfırlama zaman damgası	1642251600
Retry-After	Yeniden deneme öncesi bekleme süresi (saniye)	3600

Hata Yönetimi İçin En İyi Uygulamalar

JavaScript Örneği

async function handleAPIResponse(response) {
  // Yanıtın başarılı olup olmadığını kontrol et
  if (!response.ok) {
    const errorData = await response.json();

    switch (response.status) {
      case 400:
        throw new ValidationError(errorData.error.message, errorData.error.details);
      case 401:
        throw new AuthenticationError('Kimlik doğrulama başarısız');
      case 403:
        throw new AuthorizationError('Yetersiz izinler');
      case 404:
        throw new NotFoundError('Kaynak bulunamadı');
      case 429:
        const retryAfter = response.headers.get('Retry-After');
        throw new RateLimitError(`Kota aşıldı. ${retryAfter} saniye sonra yeniden deneyin`);
      case 500:
      case 502:
      case 503:
      case 504:
        throw new ServerError('Sunucu hatası oluştu. Lütfen yeniden deneyin.');
      default:
        throw new APIError(`Beklenmeyen hata: ${response.status}`);
    }
  }

  return await response.json();
}

// Yeniden deneme mantığıyla kullanım
async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      return await handleAPIResponse(response);
    } catch (error) {
      if (error instanceof RateLimitError) {
        const retryAfter = parseInt(error.retryAfter) || Math.pow(2, attempt);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      if (error instanceof ServerError && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // Üssel geri çekilme
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }

      throw error;
    }
  }
}

Python Örneği

import requests
import time
from typing import Dict, Any

class APIError(Exception):
    def __init__(self, message: str, status_code: int = None, details: Dict = None):
        super().__init__(message)
        self.status_code = status_code
        self.details = details

def handle_api_response(response: requests.Response) -> Dict[str, Any]:
    """Doğru hata yönetimi ile API yanıtını işleme"""

    if response.ok:
        return response.json()

    try:
        error_data = response.json()
    except ValueError:
        error_data = {"error": {"message": response.text}}

    error_info = error_data.get("error", {})
    message = error_info.get("message", f"HTTP {response.status_code}")
    details = error_info.get("details", {})

    if response.status_code == 429:
        retry_after = response.headers.get('Retry-After', '60')
        raise APIError(f"Kota aşıldı. {retry_after} saniye sonra yeniden deneyin",
                      response.status_code, details)

    elif response.status_code >= 500:
        raise APIError(f"Sunucu hatası: {message}", response.status_code, details)

    elif response.status_code >= 400:
        raise APIError(f"İstemci hatası: {message}", response.status_code, details)

    raise APIError(f"Beklenmeyen hata: {message}", response.status_code, details)

def api_call_with_retry(url: str, method: str = 'GET', max_retries: int = 3, **kwargs) -> Dict[str, Any]:
    """Otomatik yeniden deneme mantığı ile API çağrısı yap"""

    for attempt in range(1, max_retries + 1):
        try:
            response = requests.request(method, url, **kwargs)
            return handle_api_response(response)

        except APIError as e:
            if e.status_code == 429:
                retry_after = int(e.details.get('retryAfter', 60))
                time.sleep(retry_after)
                continue

            elif e.status_code >= 500 and attempt < max_retries:
                delay = 2 ** attempt  # Üssel geri çekilme
                time.sleep(delay)
                continue

            raise

    raise APIError(f"Maksimum yeniden deneme sayısı ({max_retries}) aşıldı")

Sonraki Adımlar

Yanıt formatlarını şimdi anladığınıza göre, bu desenleri uygulamalı görmek için Actions, Blocks veya Datasets gibi belirli API bölümlerini keşfedin.