REST API Tasarımı Öğrenme Rehberi: URL'den Dokümantasyona 30 Yazı

REST API tasarımı hangi kararlardan oluşur?

Bir API'yi tasarlamak, kod yazmadan önce bir dizi soruyu cevaplamak demektir. Hangi kaynaklar var ve URL'leri nasıl görünecek? Her işlem hangi HTTP metoduna denk geliyor? Başarı ve hata durumlarında hangi durum kodları dönecek? Hata gövdesi her uç noktada aynı biçimde mi? Uzun listeler nasıl parçalanacak? API değiştiğinde eski istemciler ne olacak? Kim, hangi kimlik bilgisiyle erişecek? Aşağıdaki tablo bu soruları alanlara ayırır; serinin grupları da aşağı yukarı bu sırayı izler.

Tablodaki kararlar birbirine bağlıdır. Örneğin sayfalama yanıtının nerede duracağı JSON zarfı kararına, hata gövdesinin biçimi durum kodu seçimine, sürümleme yöntemi de URL tasarımına dokunur. Bu yüzden seriyi baştan sona okumak, tek tek yazıları rastgele okumaktan daha tutarlı bir sonuç verir.

Bir API'yi tasarlarken izleyebileceğiniz sıra

Seri boyunca küçük bir mağaza API'sini örnek alıyoruz: kullanicilar, urunler, siparisler, yer yer de yazilar ve yorumlar. Türkçe kaynak adları kullanmak bir tercihtir; İngilizce /users, /orders adları da aynı ölçüde yaygındır ve kurallar iki durumda da aynıdır. Bu örnek üzerinden önerdiğimiz tasarım sırası şöyledir:

• Kaynakları çıkarın: iş alanındaki isimleri (kullanıcı, ürün, sipariş) listeleyin, aralarındaki sahiplik ilişkilerini not edin.
• URL'leri belirleyin: her kaynak için bir koleksiyon ve bir tekil kaynak adresi tanımlayın, iç içe yolları kısa tutun.
• Metotları ve durum kodlarını eşleyin: her uç nokta için başarılı yanıtın kodunu ve olası hata kodlarını yazın.
• Gövdeleri tasarlayın: istek alanlarını, yanıt alanlarını, tarih biçimini ve alan adlandırma kuralını sabitleyin.
• Hata biçimini seçin: bütün uç noktalarda aynı hata gövdesini kullanacağınız tek bir biçim belirleyin.
• Koleksiyonlara sayfalama, filtreleme ve sıralama ekleyin: sınırsız liste dönen uç nokta bırakmayın.
• Sürümleme ve kimlik doğrulama yöntemini belirleyin: ilk sürümden itibaren /v1 gibi bir önek ve Authorization başlığı kullanın.
• Belgeleyin ve kontrol edin: OpenAPI belgesini üretin, yayından önce kontrol listesinden geçin.

Bu adımların sonunda tek bir istek ve yanıt çifti, verdiğiniz kararların hepsini birden gösterir. Aşağıdaki örnekte sürüm öneki, çoğul kaynak adı, Bearer kimlik bilgisi, JSON gövdesi, 201 durum kodu ve yeni kaynağın adresini veren Location başlığı bir arada görünür:

POST /v1/siparisler HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_test_ornek123
Content-Type: application/json

{"urun_id": 7, "adet": 2}

HTTP/1.1 201 Created
Location: /v1/siparisler/1001
Content-Type: application/json

{"id": 1001, "urun_id": 7, "adet": 2, "durum": "beklemede", "created_at": "2026-11-07T09:30:00Z"}

Bu iki mesajdaki her ayrıntının ayrı bir yazısı var: adın neden çoğul olduğunu isimlendirme yazısında, 201 ile Location ilişkisini CRUD yazısında, created_at alanının biçimini alan adlandırma yazısında, Bearer başlığını kimlik doğrulama yazılarında bulacaksınız.

Öğrenme yolu: 30 yazı, 6 grup

Gruplar baştan sona okunacak biçimde sıralandı. Her grubun ilk yazısı o konunun temelini, sonrakiler ayrıntıları anlatır. Bir konuyu zaten biliyorsanız grubu atlayıp yalnızca ihtiyaç duyduğunuz yazıya gidebilirsiniz.

1. URL tasarımı

• REST API nedir? Kaynak odaklı tasarım: Kaynak, temsil ve tekdüze arayüz kavramlarını RFC 9110 üzerinden anlatır; eylem tabanlı URL'lerle kaynak tabanlı URL'lerin farkını örnek isteklerle gösterir.
• Endpoint isimlendirme kuralları: Neden fiil değil isim, neden çoğul, neden küçük harf kullanıldığını; Türkçe karakter, sondaki eğik çizgi ve çok kelimeli adlar gibi ayrıntıları ele alır.
• İç içe kaynaklar ve URL derinliği: İlişkili kaynakların /kullanicilar/123/yazilar biçiminde nasıl yazılacağını, derin URL'lerin nasıl düzleştirileceğini ve üst kaynağın neden doğrulanması gerektiğini anlatır.

2. Metotlar ve parametreler

• CRUD endpoint tasarımı: Koleksiyon ve tekil kaynak uç noktalarını, her işlemin metot ve durum kodu karşılığını, 201 ile Location başlığını, 204 ve 405 yanıtlarını çalışan bir örnekle kurar.
• PUT ve PATCH farkı: Tam değiştirme ile kısmi güncellemeyi, idempotentlik farkını ve JSON Merge Patch (RFC 7396) ile JSON Patch (RFC 6902) biçimlerini karşılaştırır.
• Path ve query parametresi farkı: Kimliği yolda, filtreyi, sıralamayı ve sayfalamayı sorgu dizesinde taşımanın gerekçesini ve ikisinin FastAPI'de nasıl tanımlandığını gösterir.
• Filtreleme, sıralama ve arama: role=admin gibi filtreleri, tarih aralıklarını, q= aramasını ve sort=-created_at,title sıralamasını; alanları beyaz listeyle sınırlamanın önemini anlatır.
• Toplu işlem (batch) uç noktası: Tek istekte çok kayıt oluşturma ve güncelleme gövdelerini, kısmi başarısızlıkta yanıtın nasıl kurulacağını ve toplu işlem limitini ele alır.
• Idempotency-Key kullanımı: Ağ hatasından sonra tekrarlanan POST isteğinin çift kayıt üretmesini Idempotency-Key başlığı ve sonuç önbelleğiyle nasıl engelleyeceğinizi gösterir.

3. Yanıt ve hata biçimi

• JSON yanıt yapısı: data ve meta: Tekil kaynak ile koleksiyon yanıtlarının biçimini, data ve meta zarfının ne zaman işe yaradığını ve tutarlılığın neden önemli olduğunu anlatır.
• JSON alan adlandırma ve tarih biçimi: snake_case anahtarları, created_at gibi tutarlı alan adlarını, RFC 3339 tarih biçimini ve kimlik alanının tipini RFC 8259 ile birlikte ele alır.
• İstek doğrulama: 400 ve 422 farkı: Bozuk gövde ile geçersiz alan değerini ayırmayı, Pydantic ile doğrulamayı ve FastAPI'nin varsayılan 422 yanıtının gerçek içeriğini gösterir.
• Problem Details (RFC 9457): type, title, status, detail ve instance alanlarını, application/problem+json medya tipini ve RFC 9457'nin RFC 7807'nin yerini aldığını anlatır.
• Hata mesajı formatı ve hata kodları: Problem Details dışında özel bir hata gövdesi seçenlere minimal ve ayrıntılı biçimi, makine okunur hata kodlarını ve alan bazlı hata listesini anlatır.

4. Durum kodları ve kimlik doğrulama

• Durum kodu seçimi: Senaryo bazında 200, 201, 204, 400, 404, 409, 422, 429, 500 ve 503 arasında nasıl seçim yapılacağını ve hata için neden 200 dönülmemesi gerektiğini anlatır.
• 401 ve 403 farkı: Kimlik bilgisi eksik ya da geçersiz olduğunda 401 ile WWW-Authenticate başlığını, yetki yetmediğinde 403'ü ve kaynağı 404 ile gizleme seçeneğini karşılaştırır.
• API key ile kimlik doğrulama: Servisler arası kullanımda API anahtarını Authorization: Bearer ile göndermeyi, sunucuda doğrulamayı ve anahtar önekleri fikrini RFC 6750 ile birlikte ele alır.
• JWT Bearer token ile kimlik doğrulama: Durumsuz kimlik doğrulama akışını, token üretmeyi, exp alanını ve süresi dolmuş ya da geçersiz token için 401 dönmeyi PyJWT ile çalışan kodla gösterir.

5. Sayfalama ve sürümleme

• Offset sayfalama: page ve limit: page ve limit ile offset ve limit parametrelerini, toplam sayfa hesabını, next ve prev bağlantılarını ve üst limit koymanın gerekçesini anlatır.
• Cursor sayfalama ve offset farkı: next_cursor ve has_more alanlarıyla cursor tabanlı sayfalamayı, değişen verilerde offset yönteminin sorunlarını ve hangisinin ne zaman seçileceğini karşılaştırır.
• API versiyonlama: URL ve header: /v1 önekiyle URL sürümlemeyi ve Accept başlığıyla medya tipi sürümlemesini artı ve eksileriyle anlatır, FastAPI APIRouter önekini gösterir.
• Breaking change ve geriye uyumluluk: Alan silme, yeniden adlandırma, tip değiştirme ve zorunlu alan eklemenin neden kırıcı, isteğe bağlı alan eklemenin neden uyumlu olduğunu örnek gövdelerle anlatır.
• Deprecation ve Sunset başlıkları: Eski bir sürümü kaldırırken Deprecation (RFC 9745) ve Sunset (RFC 8594) başlıklarını, ilgili Link ilişkilerini ve geçiş takvimini ele alır.

6. İleri desenler ve dokümantasyon

• Content negotiation ve Accept başlığı: Accept ve Content-Type ile içerik anlaşmasını, JSON'un varsayılan olmasını, XML seçeneğini ve 406 ile 415 durum kodlarını RFC 9110 üzerinden anlatır.
• HATEOAS nedir?: Yanıt gövdesine ilgili kaynakların bağlantılarını koymayı, RFC 8288 Link başlığını ve sayfalama bağlantılarıyla ilişkisini anlatır.
• Webhook tasarımı: Abonelik uç noktasını, user.created gibi olay adlarını, olay gövdesinin yapısını ve teslim ile tekrar denemede dikkat edilecek noktaları ele alır.
• OpenAPI ve Swagger ile dokümantasyon: OpenAPI ve Swagger kavramlarını, FastAPI'nin otomatik /docs, /redoc ve /openapi.json çıktısını ve summary, description, responses alanlarını anlatır.
• OpenAPI 3.1 YAML dosyası yazma: Elle yazılan bir OpenAPI 3.1 belgesinin info, paths, parameters, requestBody, responses ve components bölümlerini, $ref kullanımını ve doğrulayıcıyla kontrolü gösterir.
• REST API tasarım kontrol listesi: Yayından önce geçilecek maddeleri kısa gerekçeleri ve ilgili yazı bağlantılarıyla bir arada sunar; seriyi bitirdiğinizde dönüp kullanacağınız sayfadır.
• REST API tasarım hataları: Fiilli URL, tekil ad, derin yol, hata için 200, tutarsız hata gövdesi, sayfalamasız liste, her kökene açık CORS ve yanıtta sır gibi sık hataları düzeltmeleriyle birlikte toplar.

Serinin bilerek dışında bıraktığı konular

Bazı konuların sitede zaten ayrıntılı yazıları var; bu seri onları tekrar etmez, yalnızca gerektiği yerde bağlantı verir. HTTP mesajının yapısını ve her metodun güvenli (safe) ve idempotent olup olmadığını HTTP istek ve yanıt yapısı yazısında, bütün durum kodlarının genel listesini HTTP durum kodları rehberinde bulabilirsiniz. Hız sınırlama (rate limiting) algoritmaları ve 429 yanıtıyla gönderilen başlıklar API rate limiting stratejileri yazısının konusudur; bu seride ayrı bir hız sınırlama yazısı yoktur.

Güvenlik tarafında genel çerçeve REST API güvenlik rehberinde, JWT'ye yönelik saldırılar JWT güvenlik rehberinde, OAuth 2.0 ve OpenID Connect akışları OAuth2 ve OIDC rehberinde anlatılır. Tarayıcıdan gelen isteklerin kökenler arası kuralları için CORS nedir yazısına ve CORS hataları yazısına, önbellek ve koşullu istekler için Cache-Control ve ETag yazısına bakın. REST ile GraphQL'in karşılaştırması GraphQL ve REST yazısında yer alır. Tasarımı koda dökmek isterseniz Node.js ile REST API geliştirme ve FastAPI'yi Uvicorn ve Nginx ile yayınlama yazıları uygulama tarafını tamamlar.

Standart ile tasarım tercihi arasındaki fark

REST API tasarımında okuduğunuz kuralların bir kısmı standartlardan, bir kısmı ise deneyimden doğan alışkanlıklardan gelir. İkisini karıştırmak, bir tercihi tartışılmaz kural sanmanıza ya da bir standardı keyfî bir alışkanlık gibi görmenize yol açar. Seri boyunca kullandığımız ayrım şöyledir:

Bir tercihin standart olmaması onu zayıflatmaz; önemli olan bir kez seçip API'nin her yerinde aynı biçimde uygulamaktır. İstemci açısından en pahalı şey, bir uç noktada created_at, diğerinde createdAt görmek ya da bir hatanın bazen 422, bazen 200 içinde bir mesajla dönmesidir.

Seriyi nasıl okumalısınız?

REST'e yeniyseniz ilk iki grubu sırayla okuyun: kaynak kavramı ve URL tasarımı oturmadan metotlar, metotlar oturmadan da durum kodları anlamsız kalır. Var olan bir API'yi düzeltiyorsanız önce tasarım hataları yazısına göz atıp kendi API'nizdeki sorunları belirleyin, sonra ilgili gruba gidin. Yayına çıkmak üzere olan bir API için kontrol listesi en hızlı başlangıç noktasıdır.

Her yazıdaki örnekler denendi: JSON gövdeleri ayrıştırıcıyla, OpenAPI belgeleri doğrulayıcıyla kontrol edildi, Python örnekleri FastAPI'nin test istemcisiyle çalıştırıldı ve yorumlardaki çıktılar gerçek çıktılardır. Kendi denemelerinizde de aynı yöntemi kullanabilirsiniz: sunucu başlatmadan, test istemcisiyle istek gönderip durum kodunu ve başlıkları görmek tasarım kararlarını sınamanın kolay bir yoludur.

Sık Sorulan Sorular

REST API tasarımı için önce hangi yazıyı okumalıyım?

REST API nedir yazısıyla başlayın, ardından isimlendirme kuralları ve CRUD endpoint tasarımı yazılarına geçin. Bu üçü, sonraki bütün konuların dayandığı kaynak, URL ve metot kavramlarını kurar.

Bu seri yalnızca FastAPI kullananlar için mi?

Hayır. Tasarım kararları dilden bağımsızdır; FastAPI yalnızca kararları çalışan kodla göstermek için kullanılır. Ham HTTP mesajları ve JSON örnekleri her ortamda aynıdır.

Hata gövdesi için RFC 7807 mi, RFC 9457 mi?

RFC 9457 kullanın. RFC 9457, RFC 7807'yi eskitmiştir (obsoletes); eski belgelerde ve bazı kaynaklarda hâlâ 7807 adı geçer. Ayrıntılar Problem Details yazısında.

Seride hız sınırlama neden yok?

Hız sınırlama algoritmaları ve başlıkları sitede ayrı bir yazıda anlatıldığı için tekrar edilmedi: API rate limiting stratejileri. Seride 429 durum kodu yalnızca durum kodu seçimi bağlamında geçer.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: REST API nedir · CRUD endpoint tasarımı · Tasarım kontrol listesi · HTTP istek ve yanıt yapısı · HTTP durum kodları