REST API Tasarımı: En İyi Uygulamalar ve Sık Yapılan Hatalar
Geliştiricilerin seveceği API'lar tasarlayın. REST kurallarını, hata yönetimini, versiyonlamayı ve dokümantasyon stratejilerini öğrenin.

Gönderdiğim ilk liste uç noktası, basit bir JSON dizisi döndürüyordu. Birkaç ay sorunsuz çalıştı. Ancak tablo birkaç yüz bin satırı aştığında uç nokta zaman aşımına uğramaya başladı, bu yüzden sayfalama (pagination) ihtiyacı doğdu. Ancak basit bir dizide "sonraki sayfa" işaretçisini koyacak bir yer yoktu. Yanıtı bir nesneye dönüştürmek, mevcut yapıyı bozan bir değişiklikti ve kullanıcılara zaten gönderilmiş olan her mobil istemci, yayın günü çalışmayı durdurdu.
Gördüğüm neredeyse her sorunlu API değişikliği, üzerinde düşünülmeyecek kadar küçük görünen bir tasarım kararıyla başladı: bir yanıt şekli, bir hata formatı, eksik bir idempotency koruması. Bu yazı, ilk istemci size bağımlı hale gelmeden önce alınması gereken kararları ele alıyor. Versiyonlama ve kimlik doğrulama konularına aşağıda bağlantılarını verdiğim ayrıntılı bölümlerde değiniliyor.
Hızlı çıkarımlar
- Kaynakları isimler olarak modelleyin, HTTP metotlarının fiili taşımasına izin verin ve URL'leri sıkıcı ve tahmin edilebilir tutun.
- Liste yanıtlarını ilk günden itibaren bir nesneye (
dataartıpage) sarın ve büyük tablolar için imleçli sayfalama (cursor pagination) tercih edin. - Hataları, istemcilerin üzerinde işlem yapabileceği sabit bir
typeile tek bir makine tarafından okunabilir şekilde (RFC 9457 problem details) döndürün. - Güvenli olmayan işlemleri, bir
Idempotency-Keybaşlığı ile tekrar denemeye karşı güvenli hale getirin. - OpenAPI ile dokümante edin ve her uç nokta için gerçek istek ve yanıt örnekleri ekleyin.
Kaynakları nasıl adlandırmalı ve HTTP metotlarını nasıl kullanmalıyım?
Koleksiyonlar için çoğul isimler kullanın ve tanımlayıcıları yola (path) yerleştirin. Metot ne olduğunu söyler:
GET /orders list orders (filter, sort, paginate)
POST /orders create an order
GET /orders/{id} read one order
PATCH /orders/{id} partial update
PUT /orders/{id} replace the whole resource
DELETE /orders/{id} remove it
GET /orders/{id}/items sub-resource, one level of nesting at most
POST /orders/{id}/cancel an action that is not plain CRUD
GET /getOrders metodun zaten söylediğini tekrar eder. Fiilleri, cancel gibi CRUD'a uymayan eylemler için ayırın ve bunları bir alt yola (sub-path) POST olarak modelleyin. İç içe geçmeyi sığ tutun; iki seviyeyi geçtikten sonra, alt kaynağa filtreli kendi üst düzey rotasını verin.
Bir API hangi durum kodlarını döndürmelidir?
Sadece çalışıp çalışmadığını değil, istemciye bir sonraki adımda ne yapması gerektiğini söyleyen kodu kullanın:
- 200 başarılı bir okuma veya güncelleme için, 201 bir oluşturma için (bir
Locationbaşlığı ile), 204 döndürülecek hiçbir şey olmadığında. - 400 hatalı biçimlendirilmiş bir istek için, 422 doğrulama hatası veren iyi biçimlendirilmiş bir istek için.
- 401 çağıran kimlik doğrulaması yapmadığında, 403 kimlik doğrulaması yapılmış ancak izin verilmediğinde.
- 404 eksik bir kaynak için, 409 bir çakışma (örneğin bir kopya veya eski bir güncelleme) için.
- 429 hız sınırlaması uygulandığında, bir
Retry-Afterbaşlığı ile. - 500 yalnızca gerçekten sizin tarafınızdan kaynaklanan hatalar için.
Asla gövdesinde bir hata ile 200 döndürmeyin. İstemciler, proxy'ler ve izleme araçları hepsi durum satırına güvenir.
Liste uç noktalarını nasıl sayfalarım?
Offset sayfalama (?page=500), offset büyüdükçe yavaşlar ve istekler arasında veri değiştiğinde satırları atlar veya tekrarlar. İmleç (keyset) sayfalama her ikisinden de kaçınır. Görülen son satırı kodlayan opak bir imleç döndürün:
{
"data": [{ "id": 1042, "status": "paid" }],
"page": { "has_more": true, "next_cursor": "eyJpZCI6MTA0Mn0" }
}
const encodeCursor = (id: number) => Buffer.from(JSON.stringify({ id })).toString("base64url");
const decodeCursor = (cursor: string): number => JSON.parse(Buffer.from(cursor, "base64url").toString()).id;
app.get("/orders", async (req, res) => {
const limit = Math.min(Number(req.query.limit) || 20, 100);
const after = req.query.cursor ? decodeCursor(String(req.query.cursor)) : null;
const { rows } = await db.query(
`SELECT id, status FROM orders
WHERE ($1::bigint IS NULL OR id < $1)
ORDER BY id DESC
LIMIT $2`,
[after, limit + 1], // fetch one extra row to know if there is a next page
);
const hasMore = rows.length > limit;
const data = rows.slice(0, limit);
res.json({
data,
page: { has_more: hasMore, next_cursor: hasMore ? encodeCursor(data[data.length - 1].id) : null },
});
});
Her zaman limit değerini sınırlayın ve çözümlenemeyen bir imleç için 400 döndürün. Sıralama sütununun bir indekse ihtiyacı vardır, aksi takdirde sorgu offset'ten daha iyi olmaz.
Hata yanıtları nasıl görünmeli?
Tek bir şekil seçin ve her yerde kullanın. RFC 9457 "problem details" bir standarttır, bu nedenle istemci kütüphaneleri bunu zaten anlar:
{
"type": "https://api.example.com/problems/validation-error",
"title": "Validation failed",
"status": 422,
"detail": "One field is invalid.",
"errors": [{ "field": "quantity", "message": "must be at least 1" }]
}
Bunu Content-Type: application/problem+json ile gönderin. Önemli alan type'tır: bu, istemcilerin üzerinde dallanabileceği sabit bir tanımlayıcıdır, oysa insan tarafından okunabilir title ve detail serbestçe değişebilir. Bir geliştiricinin çağrıyı düzeltmesine yardımcı olacak mesajlar yazın ve asla yığın izleri (stack traces) veya dahili tablo adları eklemeyin. Bunun sunucu tarafı kısmı, neyin açığa çıkarılacağına ve neyin günlüğe kaydedileceğine karar verme, hata işleme desenleri bölümünde ele alınmıştır.
POST isteklerini tekrar denemeye karşı nasıl güvenli hale getiririm?
Sunucu işi bitirdikten sonra ağlar başarısız olabilir. Korumasız bir ödeme isteğini tekrar deneyen bir istemci, müşteriyi iki kez ücretlendirir. İstemcilerden benzersiz bir Idempotency-Key göndermelerini isteyin ve ilk yanıtı bu anahtar altında saklayın:
app.post("/payments", async (req, res) => {
const key = req.header("Idempotency-Key");
if (!key) {
return res.status(400).type("application/problem+json").json({
type: "about:blank",
title: "Missing Idempotency-Key header",
status: 400,
});
}
const saved = await store.get(key);
if (saved) return res.status(saved.status).json(saved.body); // replay, do not charge again
const result = await createPayment(req.body);
await store.set(key, { status: 201, body: result }, 24 * 3600);
res.status(201).json(result);
});
Üretimde, işi yapmadan önce anahtarı atomik olarak talep edin (örneğin Redis SET NX ile), böylece iki eşzamanlı yeniden deneme de kontrolü geçemez.
Versiyonlama, kimlik doğrulama ve dokümantasyon nereye sığar?
İlk sürümden önce versiyonlama kurallarınızı belirleyin; İstemcileri bozmayan API versiyonlama stratejileri nelerin bozucu değişiklik sayıldığını kapsar ve OpenAPI diff ve Pact ile CI'da bozucu değişiklikleri yakalama bunu nasıl uygulayacağınızı gösterir. Kimlik doğrulama için, API anahtarları sunucudan sunucuya çağrılar için uygundur, JWT'ler durumsuz istemciler için uygundur ve OAuth 2.0 üçüncü taraf erişimi içindir; bu ödünleşimler kimlik doğrulama desenleri: oturum, JWT ve OAuth bölümünde açıklanmıştır.
Koda bitişik duran bir OpenAPI dosyası ile dokümante edin ve her uç nokta için gerçek bir istek ve yanıt örneği ekleyin. Geliştiricilerin ilk kopyaladığı şeyler örneklerdir.
Hangi API tasarım hataları en çok destek talebine neden olur?
- HTTPS Yokluğu. Üretimde her şeyi şifreleyin, istisna yok.
- Çok fazla veri döndürmek. Bir veritabanı satırını doğrudan serileştirmek, parola hash'leri ve dahili bayraklar gibi alanları sızdırır. Açık yanıt türlerine eşleyin.
- Hız sınırlaması yokluğu. Hatalı bir istemci döngüsü herkesi çökertabilir.
Retry-Afterile429döndürün. - Kötü hata mesajları. Detaysız "Bad request" (Hatalı istek), bir dakikalık bir düzeltmeyi bir destek yazışmasına dönüştürür.
- Tutarsız şekiller. Bazı listeler sarılmış, diğerleri çıplak; bazı hatalar
message, diğerlerierror. "İyi API tasarımı"nın çoğu tutarlılık demektir.
Bu hafta ne yapmalıyım?
En yoğun liste uç noktanızı açın ve üç şeyi kontrol edin: yanıt, büyümeye açık bir nesne mi, sınırlı bir limit ile sayfalanıyor mu ve hataları tek bir belgelenmiş şekil mi kullanıyor? Değişiklik hala ucuzken ilkini şimdi düzeltin ve problem-details yardımcısını bir kez yazın ki her işleyici onu yeniden kullansın. Ardından OpenAPI dosyanızı dışa aktarın ve istemcilerinizin en çok çağırdığı üç uç noktaya birer gerçek örnek ekleyin.
Uğur Kaval
Modern teknolojilerle yenilikçi çözümler geliştirmede uzmanlaşmış AI/ML Mühendisi & Full Stack Geliştirici. Otomasyon, makine öğrenmesi ve web geliştirme tutkunu.


