Merhaba arkadaşlar, bugün sizlerle uzun süredir backend projelerimde kullandığım ve başımı ağrıtmaktan kurtaran bir yapıdan bahsedeceğim. Özellikle Laravel ve Node.js ile geliştirme yaparken, frontend tarafından gelen "API'den tutarsız cevaplar geliyor" şikayetleri beni de çok yormuştu. Farklı endpoint'ler farklı formatlarda success/error dönüyor, hata mesajları bazen string bazen array oluyordu. İşte bu kaosu bitirmek için kendi standart wrapper'ımı oluşturdum.
Neden Standart Bir Yapı Şart?
Bu sorunu ilk ciddi projemde yaşadığımda gerçekten kafayı yemiştim. Frontend ekibi, her endpoint için farklı bir response formatı parse etmek zorunda kalıyordu. Bazen `{data: {...}}` bazen direkt obje dönüyorduk. Hatalarda ise durum daha vahimdi; validation hataları, auth hataları, server hataları... Hepsi farklı bir şekilde geliyordu. Bu durum hem frontend development'ı yavaşlatıyor hem de debugging'i kabusa çeviriyordu. "Artık yeter!" deyip kolları sıvadım.
Response Wrapper Sınıfım (Laravel Örneği)
İlk olarak tüm başarılı response'ları aynı kalıba sokan bir sınıf yazdım. Amacım, her zaman `data`, `message` ve `status` alanlarını içeren tutarlı bir JSON döndürmek.
Bu sınıfı kullanmak inanılmaz basitleşti. Controller'da artık şöyle yazıyorum:
Hata Mesajı Formatlama Şablonu
Sadece wrapper yetmez! Hata mesajlarının da anlamlı ve işlenebilir olması gerekiyor. Frontend'in hatayı kullanıcıya gösterebilmesi veya loglayabilmesi için standart bir hata objesi oluşturdum. Burada önemli olan, 'code' alanı. Her hatayı bir kodla eşleştiriyorum.
Kullanımı şöyle:
Elde Ettiğim Kazanımlar
Bu yapıyı kurduktan sonra hayatım çok kolaylaştı. Frontend artık response'un formatından emin. Her zaman `status` alanına bakıp işlemin başarılı mı hatalı mı olduğunu anlıyor. Hata durumunda, gelen `error.code` ile hatanın kaynağını loglayabiliyor veya kullanıcıya daha spesifik bir mesaj gösterebiliyor. API dokümantasyonu yazmak da inanılmaz derecede standartlaştı.
Siz backend geliştiriciler, API response'larınızı nasıl standartlaştırıyorsunuz? Laravel için `Resources` & `Collections` mı kullanıyorsunuz yoksa benimki gibi merkezi bir helper mı? Ya da Node.js'te (Express) benzer bir yapı kurmak için middleware veya utility fonksiyonlar mı yazıyorsunuz? Deneyimlerinizi ve farklı yöntemlerinizi yorumlarda paylaşırsanız çok sevinirim!
Neden Standart Bir Yapı Şart?Bu sorunu ilk ciddi projemde yaşadığımda gerçekten kafayı yemiştim. Frontend ekibi, her endpoint için farklı bir response formatı parse etmek zorunda kalıyordu. Bazen `{data: {...}}` bazen direkt obje dönüyorduk. Hatalarda ise durum daha vahimdi; validation hataları, auth hataları, server hataları... Hepsi farklı bir şekilde geliyordu. Bu durum hem frontend development'ı yavaşlatıyor hem de debugging'i kabusa çeviriyordu. "Artık yeter!" deyip kolları sıvadım.
Response Wrapper Sınıfım (Laravel Örneği)İlk olarak tüm başarılı response'ları aynı kalıba sokan bir sınıf yazdım. Amacım, her zaman `data`, `message` ve `status` alanlarını içeren tutarlı bir JSON döndürmek.
PHP:
<?php
namespace App\Helpers;
class ApiResponse
{
public static function success($data = null, string $message = 'İşlem başarılı.', int $httpCode = 200)
{
return response()->json([
'status' => 'success',
'message' => $message,
'data' => $data,
], $httpCode);
}
public static function error(string $message = 'Bir hata oluştu.', $errors = null, int $httpCode = 400)
{
$response = [
'status' => 'error',
'message' => $message,
];
// Hata detaylarını sadece development ortamında veya özel durumlarda göster
if ($errors !== null && config('app.debug')) {
$response['errors'] = $errors;
}
return response()->json($response, $httpCode);
}
}Bu sınıfı kullanmak inanılmaz basitleşti. Controller'da artık şöyle yazıyorum:
PHP:
// Başarılı Response
return ApiResponse::success($user, 'Kullanıcı başarıyla getirildi.');
// Başarılı ama ekstra mesajlı
return ApiResponse::success($posts, 'Postlar listelendi.', 201);
// Hata Response'u
return ApiResponse::error('Geçersiz token.', null, 401);
// Validation Hatası (Laravel Validator'dan gelen $errors)
return ApiResponse::error('Doğrulama hatası.', $validator->errors(), 422);Sadece wrapper yetmez! Hata mesajlarının da anlamlı ve işlenebilir olması gerekiyor. Frontend'in hatayı kullanıcıya gösterebilmesi veya loglayabilmesi için standart bir hata objesi oluşturdum. Burada önemli olan, 'code' alanı. Her hatayı bir kodla eşleştiriyorum.
PHP:
public static function formattedError(string $internalCode, string $userMessage, $technicalDetails = null, int $httpCode = 400)
{
$errorMap = [
'AUTH_001' => 'Geçersiz kimlik bilgileri.',
'VAL_001' => 'Girilen veriler geçersiz.',
'DB_001' => 'Veritabanı işlemi sırasında hata.',
// ... Diğer hata kodları
];
$response = [
'status' => 'error',
'message' => $userMessage,
'error' => [
'code' => $internalCode,
'description' => $errorMap[$internalCode] ?? 'Tanımsız hata kodu.',
]
];
// Debug modunda teknik detayları da ekle (stack trace, exception mesajı vb.)
if (config('app.debug') && $technicalDetails) {
$response['error']['debug'] = $technicalDetails;
}
return response()->json($response, $httpCode);
}Kullanımı şöyle:
PHP:
try {
// ... riskli işlem
} catch (AuthenticationException $e) {
return ApiResponse::formattedError('AUTH_001', 'Giriş yapılamadı.', $e->getMessage(), 401);
} catch (ValidationException $e) {
return ApiResponse::formattedError('VAL_001', 'Lütfen form alanlarını kontrol edin.', $e->errors(), 422);
}Bu yapıyı kurduktan sonra hayatım çok kolaylaştı. Frontend artık response'un formatından emin. Her zaman `status` alanına bakıp işlemin başarılı mı hatalı mı olduğunu anlıyor. Hata durumunda, gelen `error.code` ile hatanın kaynağını loglayabiliyor veya kullanıcıya daha spesifik bir mesaj gösterebiliyor. API dokümantasyonu yazmak da inanılmaz derecede standartlaştı.
Siz backend geliştiriciler, API response'larınızı nasıl standartlaştırıyorsunuz? Laravel için `Resources` & `Collections` mı kullanıyorsunuz yoksa benimki gibi merkezi bir helper mı? Ya da Node.js'te (Express) benzer bir yapı kurmak için middleware veya utility fonksiyonlar mı yazıyorsunuz? Deneyimlerinizi ve farklı yöntemlerinizi yorumlarda paylaşırsanız çok sevinirim!