Yanıt Formatları

API Yanıt Yapılarını Anlama

mindzieAPI yanıt formatları, durum kodları, hata yönetimi kalıpları 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 formatını 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": {
    // Sayfalı yanıtlarda 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",
    "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ı.

Sayfalama

Büyük veri seti yanıtları için tutarlı sayfalama formatı.

HTTP Durum Kodları

Başarı Kodları (2xx)

Kod	Durum	Açıklama	Kullanım
200	Tamam	İstek başarılı, veri döndü	GET istekleri, başarılı işlemler
201	Oluşturuldu	Kaynak başarıyla oluşturuldu	Yeni kaynak oluşturan POST istekleri
202	Kabul Edildi	İstek asenkron işleme kabul edildi	Uzun süren işlemler, kuyruklanan görevler
204	İçerik Yok	İstek başarılı, veri döndürülmedi	DELETE istekleri, veri döndürmeyen güncellemeler

İstemci Hata Kodları (4xx)

Kod	Durum	Açıklama	Yaygın Nedenler
400	Geçersiz İstek	Geçersiz istek formatı veya parametreler	Eksik başlıklar, geçersiz JSON, bozuk veri
401	Yetkisiz	Kimlik doğrulama gerekli veya başarısız	Eksik/geçersiz token, süresi dolmuş kimlik bilgileri
403	Yasak	Geçerli kimlik bilgisi ancak yetersiz izinler	Sınırlı kullanıcı erişimi, yanlış tenant/proje
404	Bulunamadı	İstenen kaynak mevcut değil	Geçersiz uç nokta, var olmayan kaynak ID'si
422	İşlenemeyen Varlık	Format geçerli ancak iş mantığı doğrulaması başarısız	Geçersiz iş kuralları, kısıtlama ihlalleri
429	Çok Fazla İstek	İstek oranı sınırı aşıldı	Zaman diliminde çok fazla API çağrısı

Sunucu Hata Kodları (5xx)

Kod	Durum	Açıklama	Eylem
500	Dahili Sunucu Hatası	Beklenmeyen sunucu hatası	Üssel geri çekme ile yeniden dene
502	Kötü Ağ Geçidi	Yukarı akış servis hatası	Servis durumunu kontrol et, daha sonra yeniden dene
503	Hizmet Kullanılamıyor	Servis geçici olarak kullanılamıyor	Gecikmeli tekrar dene, bakım durumu kontrolü
504	Ağ Geçidi Zaman Aşımı	İstek zaman aşımına uğradı	Zaman aşımını artır, isteği optimize et

Yaygın Yanıt Kalıpları

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
  }
}

Sayfalama 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 kümesi analizi işleniyor..."
}

Hata Yanıtı Detayları

Doğrulama Hatası

{
  "error": {
    "code": "validation_failed",
    "message": "İstek doğrulaması başarısız",
    "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 tokeni geçersiz veya süresi dolmuş",
    "details": {
      "tokenType": "bearer",
      "expiresAt": "2024-01-15T09:00:00Z",
      "suggestion": "Lütfen erişim tokeninizi yenileyin"
    },
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_12345"
  }
}

Oran Sınırı Hatası

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Bu uç nokta için oran 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	Tekil istek tanımlayıcısı	req_12345678
X-Response-Time	Sunucu işlem süresi	145ms
X-API-Version	Kullanılan API versiyonu	1.0.0

Oran Sınırı Başlıkları

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

Hata Yönetimi İçin En İyi Uygulamalar

JavaScript Örneği

async function handleAPIResponse(response) {
  // Yanıt başarılı mı 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(`Oran sınırına ulaşıldı. ${retryAfter} saniye sonra tekrar deneyin`);
      case 500:
      case 502:
      case 503:
      case 504:
        throw new ServerError('Sunucu hatası oluştu. Lütfen tekrar deneyin.');
      default:
        throw new APIError(`Beklenmeyen hata: ${response.status}`);
    }
  }

  return await response.json();
}

// Yeniden deneme mantığı ile 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 çekme
        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]:
    """API yanıtını uygun hata yönetimi ile 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"Oran sınırlamasına takıldı. {retry_after} saniye sonra tekrar 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 çekme
                time.sleep(delay)
                continue

            raise

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

API Veri Aktarım Nesneleri (DTO)

Aşağıda mindzieAPI uç noktalarında kullanılan önemli DTO'lar yer almaktadır.

Tenant DTO'ları

TenantListItemDto

{
  "tenantId": "12345678-1234-1234-1234-123456789012",
  "name": "acme-corp",
  "displayName": "Acme Corporation",
  "description": "Ana tenant",
  "caseCount": 50000,
  "maxUserCount": 100,
  "maxAnalystCount": 20,
  "analystCount": 12,
  "userCount": 45,
  "preRelease": false,
  "isAcademic": false,
  "autoload": true,
  "dateCreated": "2024-01-15T10:30:00Z",
  "isDisabled": false
}

TenantDetailDto

{
  "tenantId": "12345678-1234-1234-1234-123456789012",
  "name": "acme-corp",
  "displayName": "Acme Corporation",
  "description": "Ana tenant",
  "isAcademic": false,
  "preRelease": false,
  "maxUserCount": 100,
  "maxAnalystCount": 20,
  "maxCases": 100000,
  "dateCreated": "2024-01-15T10:30:00Z",
  "isDisabled": false
}

TenantUpdatedDto

{
  "tenantId": "12345678-1234-1234-1234-123456789012",
  "name": "acme-corp",
  "displayName": "Acme Corporation Güncellendi",
  "message": "'acme-corp' tenant başarıyla güncellendi",
  "isDisabled": false
}

Kullanıcı (User) DTO'ları

UserListItemDto

{
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "john.smith@example.com",
  "displayName": "John Smith",
  "firstName": "John",
  "lastName": "Smith",
  "roleName": "Analyst",
  "disabled": false,
  "isServiceAccount": false,
  "homeTenantId": null,
  "homeTenantName": null,
  "lastLogin": "2024-01-15T10:30:00Z",
  "tenantCount": 2,
  "tenantNames": "acme-corp, globex-inc",
  "dateCreated": "2024-01-01T00:00:00Z"
}

UserCreatedDto

{
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "john.smith@example.com",
  "displayName": "John Smith",
  "message": "Kullanıcı başarıyla oluşturuldu"
}

Proje (Project) DTO'ları

ProjectReturn

{
  "projectId": "87654321-4321-4321-4321-210987654321",
  "tenantId": "12345678-1234-1234-1234-123456789012",
  "projectName": "Satın Alma Siparişi Analizi",
  "projectDescription": "P2P iş akışı süreç madenciliği analizi",
  "dateCreated": "2024-01-15T10:30:00Z",
  "dateModified": "2024-01-20T14:45:00Z",
  "createdBy": "kullanıcı-guid",
  "modifiedBy": "kullanıcı-guid",
  "isActive": true,
  "datasetCount": 3,
  "investigationCount": 5,
  "dashboardCount": 2,
  "userCount": 8
}

ProjectSummaryReturn

{
  "projectId": "87654321-4321-4321-4321-210987654321",
  "projectName": "Satın Alma Siparişi Analizi",
  "projectDescription": "Süreç madenciliği analizi",
  "dateCreated": "2024-01-15T10:30:00Z",
  "dateModified": "2024-01-20T14:45:00Z",
  "statistics": {
    "totalDatasets": 3,
    "totalInvestigations": 5,
    "totalDashboards": 2,
    "totalNotebooks": 12,
    "totalUsers": 8
  }
}

ProjectUserReturn

{
  "permissionId": "11111111-1111-1111-1111-111111111111",
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "john.smith@example.com",
  "displayName": "John Smith",
  "isOwner": true,
  "dateAssigned": "2024-01-15T10:30:00Z"
}

ProjectThumbnailReturn

{
  "projectId": "87654321-4321-4321-4321-210987654321",
  "hasThumbnail": true,
  "base64Image": "data:image/jpeg;base64,/9j/4AAQ..."
}

ProjectImportReturn

{
  "success": true,
  "projectId": "99999999-9999-9999-9999-999999999999",
  "projectName": "İçe Aktarılan Proje",
  "datasetsImported": 2,
  "investigationsImported": 3,
  "dashboardsImported": 1,
  "errorMessage": null,
  "message": "Proje başarıyla içe aktarıldı"
}

İnceleme (Investigation) DTO'ları

InvestigationReturn

{
  "investigationId": "11111111-2222-3333-4444-555555555555",
  "projectId": "87654321-4321-4321-4321-210987654321",
  "investigationName": "Sipariş Analizi",
  "investigationDescription": "Sipariş iş akışı süreç madenciliği analizi",
  "datasetId": "12345678-1234-1234-1234-123456789012",
  "dateCreated": "2024-01-15T10:30:00Z",
  "dateModified": "2024-01-20T14:45:00Z",
  "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "modifiedBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "investigationOrder": 1.0,
  "isUsedForOperationCenter": false,
  "investigationFolderId": null,
  "notebookCount": 3
}

InvestigationListReturn

{
  "investigations": [
    {
      "investigationId": "11111111-2222-3333-4444-555555555555",
      "projectId": "87654321-4321-4321-4321-210987654321",
      "investigationName": "Sipariş Analizi",
      "datasetId": "12345678-1234-1234-1234-123456789012",
      "notebookCount": 3
    }
  ],
  "totalCount": 5,
  "page": 1,
  "pageSize": 50
}

CreateInvestigationRequest

{
  "investigationName": "Sipariş Analizi",
  "investigationDescription": "Süreç madenciliği analizi",
  "datasetId": "12345678-1234-1234-1234-123456789012",
  "isUsedForOperationCenter": false
}

UpdateInvestigationRequest

{
  "investigationName": "Güncellenmiş Analiz Adı",
  "investigationDescription": "Güncellenmiş açıklama",
  "isUsedForOperationCenter": true
}

Not Defteri (Notebook) DTO'ları

NotebookReturn

{
  "notebookId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "investigationId": "11111111-2222-3333-4444-555555555555",
  "name": "Ana",
  "description": "Birincil analiz not defteri",
  "dateCreated": "2024-01-15T10:30:00Z",
  "dateModified": "2024-01-20T14:45:00Z",
  "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "modifiedBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "notebookType": 0,
  "notebookOrder": 1.0,
  "lastExecutionDuration": 2.5,
  "blockCount": 12
}

NotebookListReturn

{
  "notebooks": [
    {
      "notebookId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "investigationId": "11111111-2222-3333-4444-555555555555",
      "name": "Ana",
      "notebookOrder": 1.0,
      "blockCount": 12
    }
  ],
  "totalCount": 3
}

Sonraki Adımlar

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