E
EVDSOFT

Yanıt Standartları

Tüm EVDSOFT servisleri tarafından kullanılan standart API yanıt formatları.

Genel Bakış

EVDSOFT platformundaki tüm servisler, tutarlı ve öngörülebilir API yanıtları sağlamak için standart bir format kullanır. Bu standardizasyon, istemci tarafında hata yönetimini ve veri işlemeyi kolaylaştırır.

Tutarlılık

Tüm servisler aynı yanıt formatını kullanır. Platform, Auth, Mail, SMS ve Audit servisleri aynı yapıda yanıt döner.

Başarılı Yanıtlar

Başarılı işlemlerde success: true ile birlikte data alanı döner:

Tekil Kayıt

success-response.json
{
  "success": true,
  "data": {
    "id": "proj_abc123",
    "name": "Example Project",
    "status": "active"
  },
  "timestamp": "2024-02-15T10:30:00Z"
}

Liste Yanıtı (Sayfalama ile)

list-response.json
{
  "success": true,
  "data": [
    { "id": "proj_abc123", "name": "Project A" },
    { "id": "proj_xyz789", "name": "Project B" }
  ],
  "meta": {
    "total": 25,
    "page": 1,
    "limit": 10,
    "totalPages": 3
  },
  "timestamp": "2024-02-15T10:30:00Z"
}

Hata Yanıtları

Hatalı işlemlerde success: false ile birlikte error alanı döner:

Detaylı Hata (Validasyon)

validation-error.json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "İstek doğrulaması başarısız oldu.",
    "details": [
      {
        "field": "email",
        "message": "Geçerli bir e-posta adresi giriniz."
      },
      {
        "field": "password",
        "message": "Şifre en az 8 karakter olmalıdır."
      }
    ]
  },
  "timestamp": "2024-02-15T10:30:00Z"
}

Basit Hata

simple-error.json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Belirtilen kaynak bulunamadı."
  },
  "timestamp": "2024-02-15T10:30:00Z"
}

HTTP Durum Kodları

Kullanılan HTTP durum kodları ve anlamları:

KodDurumAçıklama
200OKİstek başarılı
201CreatedKayıt başarıyla oluşturuldu
204No Contentİşlem başarılı, içerik yok (silme işlemleri)
400Bad RequestGeçersiz istek (validasyon hatası)
401UnauthorizedKimlik doğrulama gerekli
403ForbiddenErişim izni yok
404Not FoundKaynak bulunamadı
500Server ErrorSunucu hatası

Sayfalama

Liste endpoint'leri sayfalama destekler. Aşağıdaki query parametreleri kullanılır:

  • page: Sayfa numarası (varsayılan: 1)
  • limit: Sayfa başına kayıt sayısı (varsayılan: 10, max: 100)
  • sort: Sıralama alanı (örn: createdAt)
  • order: Sıralama yönü (asc veya desc)

Örnek

GET /api/projects?page=2&limit=20&sort=createdAt&order=desc

TypeScript Tipleri

İstemci uygulamalarında kullanılabilecek TypeScript tip tanımları:

api-types.ts
1// Başarılı yanıt tipi
2interface ApiResponse<T> {
3  success: true;
4  data: T;
5  meta?: {
6    total: number;
7    page: number;
8    limit: number;
9    totalPages: number;
10  };
11  timestamp: string;
12}
13 
14// Hata yanıt tipi
15interface ApiErrorResponse {
16  success: false;
17  error: {
18    code: string;
19    message: string;
20    details?: Array<{
21      field: string;
22      message: string;
23    }>;
24  };
25  timestamp: string;
26}
27 
28// Birleşik tip
29type ApiResult<T> = ApiResponse<T> | ApiErrorResponse;
30 
31// Kullanım örneği
32async function fetchProject(id: string): Promise<ApiResult<Project>> {
33  const response = await fetch(`/api/projects/${id}`);
34  return response.json();
35}
36 
37// Type guard
38function isSuccess<T>(result: ApiResult<T>): result is ApiResponse<T> {
39  return result.success === true;
40}
41 
42// Kullanım
43const result = await fetchProject('proj_123');
44if (isSuccess(result)) {
45  console.log(result.data.name);
46} else {
47  console.error(result.error.message);
48}
Hata YönetimiAPI Referansı