API hata sözleşmesi: istemciye anlamlı hata döndürmek
API hata yanıtlarını tutarlı bir sözleşmeye bağlamak, istemci geliştirmeyi ve hata ayıklamayı nasıl kolaylaştırır: hata yapısı, hata kodları, versiyonlama.
Kısaca
API hata sözleşmesi, her hata yanıtına tek bir şema verir: sabit ve makine tarafından okunabilir bir kod, insan için bir mesaj ve isteğe bağlı alan bazlı ayrıntılar. Durum kodu tek başına neyin ters gittiğini söylemez; istemci yalnızca koda güvenerek dallanabilir.
API tasarımında başarılı yanıtlara harcanan özen, hata yanıtlarına çoğunlukla yansımıyor. İstemci bir hata aldığında ne döneceğini bilmiyorsa, ya her şeyi genel bir hata mesajıyla yutmak zorunda kalıyor ya da her uç noktanın hatalarını ayrı ayrı öğreniyor. Bu ikisi de iyi bir sözleşme değil.
Hatayı yanıt tasarımının ayrılmaz bir parçası olarak düşünmek gerekiyor. Başarılı yanıtın şeması varsa, hata yanıtının da şeması olmalı.
HTTP durum kodları neden yeterli değil?
HTTP durum kodları önemli ama tek başlarına yetersiz. 422 Unprocessable Entity (RFC 9110: HTTP Semantics, June 2022 içinde adı Unprocessable Content olarak değişti) isteğin doğrulama hatası aldığını söylüyor; hangi alan hatalı, neden hatalı — bunu söylemiyor. 500 Internal Server Error sunucunun hata verdiğini söylüyor; ne hata, nasıl bir hata — söylemiyor.
İstemciyi geliştiren kişi (siz veya bir başkası) o durum kodunu yorumlamak için ek bilgiye ihtiyaç duyuyor. O bilgiyi yanıt gövdesinde standart bir biçimde vermek sözleşmenin işi.
Tutarlı bir hata yapısı
Birkaç projede denediğim ve üzerinde karar kıldığım bir yapı şu:
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Gönderilen veriler doğrulanamadı.",
"details": [
{
"field": "email",
"message": "Geçerli bir e-posta adresi giriniz."
},
{
"field": "phone",
"message": "Telefon numarası zorunludur."
}
]
}
}
Bu yapıda üç katman var:
code: Machine-readable sabit bir hata kodu. İstemci bu koda göre branch açabilir.message: Human-readable kısa açıklama. Hata ayıklama için.details: Varsa ek bağlam. Doğrulama hatalarında alan bazında mesajlar; diğer hatalarda boş dizi ya da alan yok.
Bugünden bir not: tam da bu sorun için artık bir standart var. RFC 9457: Problem Details for HTTP APIs, July 2023 bir “problem detail” tanımlar; amacı, “to carry machine-readable details of errors in HTTP response content to avoid the need to define new error response formats for HTTP APIs” olarak geçer. Üyeleri type, title, status, detail ve instance’tır, application/problem+json olarak sunulur ve RFC 7807’nin yerini alır. Yukarıdaki code/message/details yapısı o biçim değil, bana ait bir konvansiyon. Bugün yeni bir public API’ye başlıyorsanız önce RFC 9457’yi değerlendirin.
Laravel’de uygulamak
Laravel’de tüm hata yanıtlarını tek noktadan yönetmek için app/Exceptions/Handler.php içindeki render metodunu kullanıyorum:
<?php
namespace App\Exceptions;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Illuminate\Validation\ValidationException;
use Illuminate\Auth\AuthenticationException;
use Symfony\Component\HttpKernel\Exception\HttpException;
use Throwable;
class Handler extends ExceptionHandler
{
public function render($request, Throwable $e)
{
if ($request->expectsJson()) {
return $this->handleApiException($request, $e);
}
return parent::render($request, $e);
}
private function handleApiException($request, Throwable $e)
{
if ($e instanceof ValidationException) {
$details = collect($e->errors())
->flatMap(fn ($messages, $field) =>
collect($messages)->map(fn ($msg) => [
'field' => $field,
'message' => $msg,
])
)
->values()
->all();
return response()->json([
'error' => [
'code' => 'VALIDATION_FAILED',
'message' => 'Gönderilen veriler doğrulanamadı.',
'details' => $details,
],
], 422);
}
if ($e instanceof AuthenticationException) {
return response()->json([
'error' => [
'code' => 'UNAUTHENTICATED',
'message' => 'Bu işlem için kimlik doğrulama gereklidir.',
],
], 401);
}
if ($e instanceof HttpException) {
return response()->json([
'error' => [
'code' => 'HTTP_ERROR',
'message' => $e->getMessage() ?: 'İstek işlenemedi.',
],
], $e->getStatusCode());
}
return response()->json([
'error' => [
'code' => 'SERVER_ERROR',
'message' => 'Beklenmeyen bir hata oluştu.',
],
], 500);
}
}
Tek bir metodun tüm exception’ları karşılaması, yeni bir hata türü eklediğinizde tek bir yere bakmanızı sağlıyor.
Hata kodları için bir kural
Hata kodlarını büyük harf ve altçizgi ile tutuyorum: VALIDATION_FAILED, RESOURCE_NOT_FOUND, QUOTA_EXCEEDED. Bu kodlar istemci tarafında switch-case veya map ile işlenebilir hale geliyor. İstemci ekibi bu kodlara göre kullanıcıya farklı mesajlar gösterebilir, farklı yönlendirmeler yapabilir.
İnsan tarafından okunabilen message alanına güvenmek istemezsiniz — bu metin değişebilir, çevrilebilir. code sabittir ve sözleşmenin bir parçasıdır.
Versiyonlama ve geriye dönük uyumluluk
Hata yapısını bir kez belirleyip sonradan değiştirmek, başarılı yanıt yapısını değiştirmek kadar kırıcı olabiliyor. İstemci error.code değerini okuyarak kendi iş mantığını yönetiyorsa, o kodun adını değiştirmek istemci tarafında sessiz bir kırılmaya yol açıyor. Bu yüzden hata kodlarını sanki bir API sözleşmesinin birinci sınıf vatandaşıymış gibi ele almak gerekiyor: yeni kod eklenebilir, eski kaldırılmamalı.
Mevcut bir kodu kullanımdan kaldırmanız gerektiğinde geçiş süresi bırakmak ve bunu dokümana yansıtmak iyi bir pratik. Başarılı yanıtları versiyonlarken hata yapısını atlamak kolay bir hata.
Hata sözleşmesi ne zaman fazla karmaşıklık olur?
Küçük bir dahili servis yazıyorsanız ve tek bir istemci var, o da sizseniz, bu yapıya gerek yok. Durum kodu + kısa mesaj yeterli olabilir.
Ama birden fazla istemciniz varsa (web, mobil, harici bir ortak), ya da API’yi dışa açıyorsanız, bu sözleşme istemci geliştirme sürecini gerçekten kolaylaştırıyor. “400 aldım, ne anlama geliyor” sorusuyla harcanan zaman birikerek önemli bir maliyet oluşturuyor.
Hata yanıtları, API’nizin sözleşmesinin bir parçasıdır. Başarılı yanıtlar kadar özenle tasarlanmayı hak ediyor.
Bu konuda sorulanlar
API hata gövdelerimi RFC 7807 problem+json biçimine mi taşımalıyım?
7807 yerine onu güncelleyen RFC 9457'yi baz alın, üretimi tek bir exception handler'a toplayın ve type URI'sini sözleşme gibi yönetin.
Bu konudaki deneyler
Kaydırmalı bilgi yarışmasında skoru istemci hesaplıyor, sunucu server_nonce ve HMAC imzasıyla doğruluyor. Bu güven sorununun yapım notları.
Şu an ne yapıyor
Kaydırmalı doğru/yanlış bilgi yarışması bir mobil uygulama olarak çekirdek döngüsüyle uçtan uca çalışıyor; skoru istemci üretse de server_nonce ve HMAC imzasıyla sunucu tarafında doğrulanıyor. swipenor.com uygulamanın tanıtım sayfasıdır, oyunun kendisi değil.
Yorumlar
Yorum yapmak için GitHub hesabınızla giriş yapmanız yeterli. Yorumlar GitHub Discussions üzerinde saklanır.