Kısaca
RFC 9457 (HTTP API'leri için Sorun Detayları), API hata yanıtları için standart formattır. Özel hata formatlarını tutarlı bir yapıyla değiştirir: tür, başlık, durum, detay ve örnek. Modern PetstoreAPI, tüm hata yanıtlarında uygun içerik anlaşması ve doğrulama detaylarıyla RFC 9457'yi uygular.
Giriş
API'niz bir hata döndürür. Yanıt neye benziyor? Çoğu API gibiyseniz, kendi formatınızı icat ettiniz:
{"error": "Invalid email"}
{"message": "Not found", "code": 404}
{"success": false, "errors": ["Email required"]}
Her API'nin farklı bir hata formatı vardır. İstemcilerin her API için özel hata işleme yapması gerekir. Hataları ayrıştırmak, kullanıcılara göstermek veya hata ayıklama için kaydetmek için standart bir yol yoktur.
RFC 9457 bunu çözer. Bu, API'lerin hataları nasıl döndürmesi gerektiğini tanımlayan bir IETF standardıdır. Kendi formatınızı icat etmek yerine, istemcilerin zaten anladığı kanıtlanmış bir standardı kullanırsınız.
Eski Swagger Petstore, tutarlılık olmayan özel hata formatları kullanıyordu. Modern PetstoreAPI, tüm hata yanıtlarında RFC 9457'yi uygulayarak yapılandırılmış, makine tarafından okunabilir hata detayları sağlar.
Bu rehberde, RFC 9457'nin ne olduğunu, doğru şekilde nasıl uygulanacağını ve Modern PetstoreAPI'nin tüm hata yanıtları için bunu nasıl kullandığını öğreneceksiniz.
API Hata Sorunu
RFC 9457'den önce, her API kendi hata formatını icat ediyordu.
Yaygın Hata Formatı Varyasyonları
Format 1: Basit mesaj
{"error": "User not found"}
Format 2: Kod ve mesaj
{"code": "USER_NOT_FOUND", "message": "User not found"}
Format 3: İç içe yapı
{
"success": false,
"error": {
"type": "NotFound",
"message": "User not found"
}
}
Format 4: Hata dizisi
{
"errors": [
{"field": "email", "message": "Invalid email"}
]
}
Özel Formatlarla İlgili Sorunlar
1. Tutarsızlık: İstemcilerin her API için özel ayrıştırmaya ihtiyacı vardır.
2. Eksik bilgi: Bazı formatlarda hata kodları, bazılarında detaylar, bazılarında ise her ikisi de eksiktir.
3. Makine tarafından okunabilir yapı yok: Hataları programatik olarak işlemek zordur.
4. Kötü uluslararasılaşma: Hata mesajları İngilizce olarak kodlanmıştır.
5. Doğrulama hataları için standart yok: Her API, alan düzeyindeki hataları farklı şekilde ele alır.
RFC 9457 Nedir?
RFC 9457 (Temmuz 2023'te yayımlandı), "HTTP API'leri için Sorun Detayları"nı tanımlar. Bu, API'lerin hata yanıtlarını nasıl yapılandırması gerektiğini belirten bir IETF standardıdır.
Temel Özellikler
Standart medya türü: application/problem+json (veya application/problem+xml)
Tutarlı yapı: Tüm hatalar aynı formatı takip eder
Makine tarafından okunabilir: İstemciler hataları programatik olarak ayrıştırabilir
Genişletilebilir: Uyumluluğu korurken özel alanlar ekleyebilirsiniz
HTTP uyumlu: HTTP durum kodlarıyla entegre olur
RFC 9457 ve Özel Hatalar
Özel hata:
{"error": "Email is required"}
RFC 9457 hatası:
{
"type": "https://petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains invalid data",
"instance": "/pets",
"errors": [
{
"field": "email",
"message": "Email is required"
}
]
}
RFC 9457 sürümü şunları sağlar:
- Dokümantasyon için hata türü URL'si
- İnsan tarafından okunabilir başlık
- HTTP durum kodu
- Detaylı açıklama
- Hataya neden olan istek yolu
- Alan düzeyinde doğrulama detayları
RFC 9457 Yapısı Açıklandı
RFC 9457 beş standart alan tanımlar ve özel uzantılara izin verir.
Standart Alanlar
1. type (dize, zorunlu)
Hata türünü tanımlayan bir URI referansı. İnsan tarafından okunabilir belgelere işaret etmelidir.
"type": "https://petstoreapi.com/errors/validation-error"
Atlanırsa, varsayılan olarak about:blank olur.
2. title (dize, zorunlu)
Hata türünün kısa, insan tarafından okunabilir bir özeti. Oluşumlar arasında değişmemelidir.
"title": "Validation Error"
3. status (sayı, zorunlu)
HTTP durum kodu. İstemcilerin başlıkları ayrıştırmasına gerek kalmaması için kolaylık amacıyla dahil edilmiştir.
"status": 400
4. detail (dize, isteğe bağlı)
Hatanın bu oluşumuna özel, insan tarafından okunabilir bir açıklama.
"detail": "The email field must be a valid email address"
5. instance (dize, isteğe bağlı)
Hatanın belirli bir oluşumunu tanımlayan bir URI referansı. Genellikle istek yoludur.
"instance": "/pets/019b4132-70aa-764f-b315-e2803d882a24"
Özel Uzantılar
Ek bağlam için özel alanlar ekleyebilirsiniz:
{
"type": "https://petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"retryAfter": 42,
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:30:00Z"
}
Modern PetstoreAPI RFC 9457'yi Nasıl Uygular?
Modern PetstoreAPI, tüm hata yanıtları için RFC 9457'yi kullanır.
Örnek 1: Kaynak Bulunamadı
GET /pets/invalid-id
404 Not Found
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/not-found",
"title": "Resource Not Found",
"status": 404,
"detail": "The requested pet does not exist",
"instance": "/pets/invalid-id"
}
Örnek 2: Kimlik Doğrulama Hatası
GET /pets
401 Unauthorized
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/unauthorized",
"title": "Authentication Required",
"status": 401,
"detail": "Valid authentication credentials are required to access this resource",
"instance": "/pets"
}
Örnek 3: Hız Sınırı Aşıldı
GET /pets
429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60
{
"type": "https://docs.petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:31:00Z"
}
Tüm hata türleri için Modern PetstoreAPI hata işleme dokümantasyonuna bakın.
RFC 9457 ile Doğrulama Hataları
Doğrulama hataları, alan düzeyinde detaylara ihtiyaç duyar. RFC 9457, bunun için özel uzantılara izin verir.
Modern PetstoreAPI Doğrulama Formatı
POST /pets
400 Bad Request
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains 2 validation errors",
"instance": "/pets",
"errors": [
{
"field": "name",
"message": "Name is required",
"code": "REQUIRED_FIELD"
},
{
"field": "species",
"message": "Species must be one of: DOG, CAT, BIRD, FISH, REPTILE, OTHER",
"code": "INVALID_ENUM_VALUE",
"rejectedValue": "DRAGON"
}
]
}
Önemli Noktalar
- hatalar dizisi: Alan düzeyinde doğrulama detaylarını içerir
- alan: Geçersiz alana giden JSON yolu
- mesaj: İnsan tarafından okunabilir hata mesajı
- kod: Makine tarafından okunabilir hata kodu
- rejectedValue: Reddedilen değer (isteğe bağlı)
Bu format, istemcilerin şunları yapmasına olanak tanır:
- Formlarda alan düzeyinde hataları görüntüleme
- Geçersiz alanları vurgulama
- Belirli hata mesajları sağlama
- Hataları programatik olarak işleme
Apidog ile Hata Yanıtlarını Test Etme
Apidog, RFC 9457 uyumluluğunu test etmenize yardımcı olur.
Test Senaryosu: Doğrulama Hatası
// Apidog test script
pm.test("Returns RFC 9457 error format", () => {
const response = pm.response.json();
// Check required fields
pm.expect(response).to.have.property("type");
pm.expect(response).to.have.property("title");
pm.expect(response).to.have.property("status");
// Check status matches HTTP status
pm.expect(response.status).to.equal(pm.response.code);
// Check content type
pm.expect(pm.response.headers.get("Content-Type"))
.to.include("application/problem+json");
});
pm.test("Validation errors include field details", () => {
const response = pm.response.json();
pm.expect(response).to.have.property("errors");
pm.expect(response.errors).to.be.an("array");
response.errors.forEach(error => {
pm.expect(error).to.have.property("field");
pm.expect(error).to.have.property("message");
});
});
Test Senaryosu: Hata Türü URL'leri
pm.test("Error type URL is accessible", async () => {
const response = pm.response.json();
const typeUrl = response.type;
// Verify type URL returns documentation
const docResponse = await pm.sendRequest(typeUrl);
pm.expect(docResponse.code).to.equal(200);
});
Özel Hata Formatlarından Geçiş
Özel hata formatları kullanıyorsanız, RFC 9457'ye nasıl geçiş yapacağınız aşağıda açıklanmıştır.
Adım 1: Content-Type Başlığı Ekle
application/problem+json döndürmeye başlayın:
Content-Type: application/problem+json
Adım 2: Mevcut Alanları Eşle
Özel formatınızı RFC 9457'ye eşleyin:
Önce:
{
"error": "USER_NOT_FOUND",
"message": "User not found"
}
Sonra:
{
"type": "https://api.example.com/errors/user-not-found",
"title": "User Not Found",
"status": 404,
"detail": "User not found"
}
Adım 3: Her İki Formatı da Destekleyin (Geçiş Dönemi)
Her iki formatı da desteklemek için içerik anlaşmasını kullanın:
Accept: application/json → Özel formatı döndürür
Accept: application/problem+json → RFC 9457 formatını döndürür
Adım 4: Özel Formatı Sonlandırın
İstemciler geçiş yaptıktan sonra, özel formatı sonlandırın ve varsayılan olarak RFC 9457'yi döndürün.
Sonuç
RFC 9457, API hata yanıtları için standart bir format sağlar. Özel hata formatlarını, istemcilerin programatik olarak ayrıştırabileceği tutarlı, makine tarafından okunabilir bir yapıyla değiştirir.
Modern PetstoreAPI, tüm hata yanıtlarında RFC 9457'yi uygulayarak, doğru doğrulama detayları, hata türü URL'leri ve HTTP durum kodlarıyla hataların nasıl doğru yapılandırılacağını gösterir.
RFC 9457 uyumluluğunu test etmek, hata yapılarını doğrulamak ve API'nizin doğru hata yanıtları döndürdüğünden emin olmak için Apidog'u kullanın.
SSS
RFC 9457 REST API'leri için gerekli mi?
Hayır, ancak önerilen standarttır. RFC 9457 kullanmak, API'nizi daha tutarlı ve istemcilerin entegre etmesi için daha kolay hale getirir.
RFC 9457'yi XML ile kullanabilir miyim?
Evet, RFC 9457 hem JSON (application/problem+json) hem de XML (application/problem+xml) formatlarını tanımlar.
Her zaman beş standart alanı da dahil etmeli miyim?
type, title ve status zorunludur. detail ve instance isteğe bağlıdır ancak daha iyi hata bağlamı için önerilir.
RFC 9457 yanıtlarına özel alanlar ekleyebilir miyim?
Evet, RFC 9457 genişletilebilir. Ek bağlam için errors, retryAfter veya traceId gibi özel alanlar ekleyebilirsiniz.
RFC 9457 ile doğrulama hatalarını nasıl işlerim?
Alan düzeyinde detaylar içeren özel bir errors dizisi ekleyin. Modern PetstoreAPI, bu deseni doğrulama hata yanıtlarında gösterir.
Hata türü URL'si neye işaret etmeli?
Hata türünü, olası nedenlerini ve nasıl düzeltileceğini açıklayan insan tarafından okunabilir belgelere işaret etmelidir.
RFC 9457 kullanırken HTTP durum kodlarını değiştirmem gerekiyor mu?
Hayır, RFC 9457 standart HTTP durum kodlarıyla çalışır. Yanıttaki status alanı, HTTP durum koduyla eşleşmelidir.
RFC 9457 uyumluluğunu nasıl test ederim?
Hata yanıt yapısını doğrulamak, gerekli alanları kontrol etmek ve içerik türlerinin RFC 9457 spesifikasyonlarıyla eşleştiğini doğrulamak için Apidog'u kullanın.