Django, JSON ve REST API Mimarisi:

Modern web geliştirmenin kalbi olan API'lar ve Django'nun bu dünyadaki yerini anlamak, seni tam donanımlı bir geliştirici yapma yolunda dev bir adımdır.

1. Temel Kavramlar: API ve JSON Nedir?

Bir web uygulaması geliştirdiğinde, sadece insanların (tarayıcı aracılığıyla) değil, diğer yazılımların da senin verine erişmesini istersin. İşte burada API devreye girer.

API (Application Programming Interface): İki yazılımın birbiriyle konuşmasını sağlayan bir elçidir. Restoran örneğini düşünürsek; sen müşterisin (Client), mutfak aşçıdır (Server) ve garson da API'dır. Siparişini mutfağa iletir ve yemeği sana getirir.
JSON (JavaScript Object Notation): API'ların konuştuğu dildir. Hafiftir, insanlar tarafından okunabilir ve makineler tarafından kolayca işlenir. Python'daki sözlüklere (dict) çok benzer.

Örnek bir JSON verisi:

JSON:
{
    "id": 1,
    "baslik": "Django ile API Geliştirme",
    "yazar": "Nuri TIRAŞ",
    "durum": "Yayında"
}

2. Django'da Veriyi JSON'a Dönüştürmek (Serialization)

Django normalde HTML sayfaları döndürmek için tasarlanmıştır. Ancak bir API yapmak istiyorsan, Python objelerini (QuerySet) JSON formatına çevirmen gerekir. Bu işleme Serialization (Serileştirme) denir.

Django Rest Framework (DRF) Neden Önemli?

Standart Django ile API yazabilirsin ama Django Rest Framework (DRF) bu işi inanılmaz kolaylaştırır. DRF bize şunları sağlar:

Serializers: Karmaşık verileri JSON'a dönüştürür.
Browsability: API'nı tarayıcı üzerinden test edebileceğin şık bir arayüz.
Authentication: Kimlerin veriye erişebileceğini yönetme.

3. Adım Adım Basit Bir API Oluşturma

Hadi, basit bir "Kitaplık" API'sı hayal edelim.

Adım 1: Modeli Tanımlama

models.py dosyasında veritabanı yapımızı kuruyoruz:

Python:
from django.db import models

class Kitap(models.Model):
    isim = models.CharField(max_length=100)
    yazar = models.CharField(max_length=100)
    sayfa_sayisi = models.IntegerField()

    def __str__(self):
        return self.isim

Adım 2: Serializer Oluşturma

serializers.py dosyasında verinin nasıl JSON olacağını belirliyoruz:

Python:
from rest_framework import serializers
from .models import Kitap

class KitapSerializer(serializers.ModelSerializer):
    class Meta:
        model = Kitap
        fields = '__all__' # Tüm alanları JSON'a dahil et

Adım 3: View (Görünüm) Yazma

views.py içinde isteklere nasıl cevap vereceğimizi yazıyoruz:

Python:
from rest_framework import generics
from .models import Kitap
from .serializers import KitapSerializer

class KitapListesi(generics.ListCreateAPIView):
    queryset = Kitap.objects.all()
    serializer_class = KitapSerializer

4. API İstek Tipleri (HTTP Methods)

API'lar ile çalışırken en sık kullanacağın 4 ana komut vardır:

Metot	Karşılığı	Açıklama
GET	Read	Verileri listelemek veya bir tanesini okumak için kullanılır.
POST	Create	Yeni bir veri (yeni bir kitap) oluşturmak için kullanılır.
PUT/PATCH	Update	Mevcut bir veriyi güncellemek için kullanılır.
DELETE	Delete	Bir veriyi silmek için kullanılır.

5. Özet ve Sonuç

Django ile API geliştirmek, veriyi bir "tablo" mantığından çıkarıp, evrensel bir format olan JSON ile tüm dünyaya sunmaktır. DRF kullanarak bu süreci güvenli, hızlı ve standartlara uygun hale getirebilirsin.

Unutma: İyi bir API, sadece veri sunan değil, aynı zamanda iyi dökümante edilmiş ve güvenliği sağlanmış bir API'dır.

Bilgisayarında Python'ın yüklü olduğunu varsayarak, en temiz şekilde bir "Kitaplık API'sı" iskeleti kuracağız.

Bu süreçte Terminal (Komut Satırı) ve bir kod editörü (VS Code vb.) kullanacağız.

1. Hazırlık: Sanal Ortam ve Kurulum

Önce projemiz için izole bir alan oluşturalım ki kütüphaneler birbirine karışmasın.

Klasör oluştur ve içine gir:

Bash:
mkdir kitaplik_projesi
cd kitaplik_projesi

Sanal ortam oluştur ve aktif et:
- Windows: python -m venv venv ve sonra venv\Scripts\activate
- Mac/Linux: python3 -m venv venv ve sonra source venv/bin/activate
Gerekli paketleri yükle:
Bash:
pip install django djangorestframework

2. Django Projesini Başlatma

Şimdi projenin ana binasını dikiyoruz.

Proje oluştur: django-admin startproject core . (Sondaki noktayı unutma, dosyaları klasörün içine yayar.)
Uygulama (App) oluştur: python manage.py startapp api

Ayarları Yap: core/settings.py dosyasını aç ve INSTALLED_APPS listesine şunları ekle:

Python:
INSTALLED_APPS = [
    ...
    'rest_framework', # API araçları
    'api',            # Bizim oluşturduğumuz app
]

3. Model ve Veritabanı (Mutfak)

api/models.py dosyasını aç ve kitaplarımızı tanımla:

Python:
from django.db import models

class Kitap(models.Model):
    isim = models.CharField(max_length=200)
    yazar = models.CharField(max_length=100)
    eklenme_tarihi = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.isim

Ardından bu değişikliği veritabanına işle:

Bash:
python manage.py makemigrations
python manage.py migrate

4. Serializer: Veriyi JSON'a Hazırlama

api/ klasörü içinde yeni bir dosya oluştur: serializers.py. Bu dosya, veritabanındaki karmaşık Python nesnesini basit bir JSON metnine dönüştürecek.

Python:
from rest_framework import serializers
from .models import Kitap

class KitapSerializer(serializers.ModelSerializer):
    class Meta:
        model = Kitap
        fields = '__all__' # id, isim, yazar, eklenme_tarihi hepsini getir

5. Views ve URL: Kapıları Açma

Son olarak, API'mızın dışarıdan erişileceği adresi ve işleyişi tanımlıyoruz.

api/views.py:

Python:
from rest_framework import generics
from .models import Kitap
from .serializers import KitapSerializer

class KitapListCreate(generics.ListCreateAPIView):
    queryset = Kitap.objects.all()
    serializer_class = KitapSerializer

core/urls.py (Ana URL dosyası):

Python:
from django.contrib import admin
from django.urls import path
from api.views import KitapListCreate

urlpatterns = [
    path('admin/', admin.site.urls),    
    path('api/kitaplar/', KitapListCreate.as_view()), # API adresimiz
]

6. Test Zamanı! 🚀

Terminalden sunucuyu çalıştır:

Bash:
python manage.py runserver

Şimdi tarayıcını aç ve şu adrese git: http://127.0.0.1:8000/api/kitaplar/

Ne Göreceksin?

Django Rest Framework'ün şık arayüzü karşına gelecek.
Alt kısımdaki formdan bir kitap ismi ve yazarı yazıp POST butonuna basarsan veritabanına kayıt eklenecek.
Üst kısımda ise eklediğin kitapların JSON formatında listelendiğini göreceksin.

Bir API'yı gerçek dünyaya hazırlayan iki kritik adım tam olarak budur: CRUD (Create, Read, Update, Delete) döngüsünü tamamlamak ve Güvenlik duvarını örmek.

1. Silme ve Güncelleme (Detail View)

Şu anki KitapListCreate görünümümüz sadece "liste" ve "oluşturma" yapıyor. Belirli bir kitabı (örneğin ID'si 5 olan) güncellemek veya silmek için yeni bir Endpoint (uç nokta) eklemeliyiz.

api/views.py dosyasına şu sınıfı ekle:

Python:
from rest_framework import generics
from .models import Kitap
from .serializers import KitapSerializer

# Mevcut listeleme sınıfın kalabilir...

class KitapDetay(generics.RetrieveUpdateDestroyAPIView):
    queryset = Kitap.objects.all()
    serializer_class = KitapSerializer

core/urls.py dosyasına gidip bu yeni görünüme bir yol (path) tanımla:

Python:
from api.views import KitapListCreate, KitapDetay

urlpatterns = [
    path('api/kitaplar/', KitapListCreate.as_view()),
    path('api/kitaplar/<int:pk>/', KitapDetay.as_view()), # <int:pk> ID'ye göre erişim sağlar
]

Artık ne yapabilirsin?

GET /api/kitaplar/1/: 1 numaralı kitabın detayını görürsün.
PUT /api/kitaplar/1/: Bilgileri güncellersin.
DELETE /api/kitaplar/1/: Kitabı silersin.

2. Token Authentication (Güvenlik Kapısı)

API'nı herkese açık bırakmak, evinin kapısını açık bırakmak gibidir. Token Authentication, kullanıcıya bir "anahtar" (token) verme işlemidir. Kullanıcı her istekte bu anahtarı gösterir, sistem de "Evet, bu bizim tanıdığımız Ahmet" der.

Adım 1: Ayarları Güncelle

core/settings.py içinde REST_FRAMEWORK ayarlarını ve yüklü uygulamaları güncelle:

Python:
INSTALLED_APPS = [
    ...
    'rest_framework.authtoken', # Token sistemini aktif eder
    ...
]

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.TokenAuthentication',
    ],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticated', # Sadece giriş yapanlar erişsin
    ],
}

Adım 2: Veritabanını Güncelle

Token tablosunun oluşması için tekrar migrate yap:

Bash:
python manage.py migrate

Adım 3: Token Almak İçin URL Tanımla

Kullanıcıların kullanıcı adı ve şifre gönderip karşılığında "Token" alabilecekleri bir adres lazım. core/urls.py içine ekle:

Python:
from rest_framework.authtoken.views import obtain_auth_token

urlpatterns = [
    ...
    path('api/token/', obtain_auth_token), # Token alma adresi
]

3. Sistemi Test Etme (Artık Kapı Kilitli!)

Şimdi http://127.0.0.1:8000/api/kitaplar/ adresine gitmeye çalışırsan "401 Unauthorized" hatası alacaksın. Çünkü artık anahtarın yok.

Peki anahtarı nasıl alacağız?

Önce bir kullanıcı (süper kullanıcı) oluştur: python manage.py createsuperuser
Postman veya terminal üzerinden /api/token/ adresine kullanıcı adını ve şifreni POST et.
Sana şöyle bir cevap dönecek: {"token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"}
Artık kitaplara erişmek için isteğinin Header (Başlık) kısmına şunu eklemelisin:
Authorization: Token 9944b0919...

Özetle Ne Yaptık?

İşlem	URL	Yetki Gerekli mi?
Giriş Yap / Token Al	`/api/token/`	Hayır (Kullanıcı adı/Şifre ile)
Kitapları Listele	`/api/kitaplar/`	Evet (Token ile)
Kitap Sil/Güncelle	`/api/kitaplar/1/`	Evet (Token ile)

API'nı yazdın, güvenliğini sağladın ama başka bir yazılımcı (veya 6 ay sonraki sen) bu API'nın hangi adreslere sahip olduğunu, hangi verileri beklediğini nereden bilecek?

İşte burada Swagger (OpenAPI) devreye girer. Swagger, API'nız için otomatik olarak yaşayan, etkileşimli ve görsel bir kullanma kılavuzu oluşturur.

Django dünyasında bu iş için en popüler ve modern kütüphane drf-spectacular'dır.

1. Kurulum ve Ayarlar

Öncelikle gerekli kütüphaneyi yükleyelim:

Bash:
pip install drf-spectacular

Ardından core/settings.py dosyasında hem uygulamayı kaydet hem de DRF'e dökümantasyon motoru olarak bunu kullanmasını söyle:

Python:
INSTALLED_APPS = [
    ...
    'drf_spectacular', # Dökümantasyon kütüphanesi
    ...
]

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
    # Daha önce eklediğimiz Authentication ayarları burada kalmalı
}

# Swagger başlığı ve açıklaması için özel ayarlar
SPECTACULAR_SETTINGS = {
    'TITLE': 'Kitaplık API Projesi',
    'DESCRIPTION': 'Kitap yönetimi için geliştirilmiş kapsamlı bir API dökümantasyonu.',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
}

2. URL Tanımlamaları

Şimdi dökümantasyonun hangi adreste görüneceğini belirleyelim. core/urls.py dosyasını şu şekilde güncelle:

Python:
from django.urls import path
from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView

urlpatterns = [
    # ... mevcut url'lerin (admin, kitaplar, token vb.) ...
    
    # Şema dosyasını indirmek için (YAML formatında)
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    
    # Swagger UI (Etkileşimli arayüz)
    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    
    # Alternatif Redoc arayüzü
    path('api/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]

3. Swagger Nasıl Kullanılır?

Sunucun çalışıyorsa (python manage.py runserver), tarayıcında http://127.0.0.1:8000/api/docs/ adresine git.

Neler Yapabilirsin?

Authorize: Sağ üstteki "Authorize" butonuna tıkla ve daha önce aldığın Token'ı Token 9944b09... formatında buraya gir. Artık kilitli kapılar sana açılacak.
Try it out: Herhangi bir endpoint'e (örneğin GET /api/kitaplar/) tıkla, "Try it out" ve ardından "Execute" de. Canlı olarak API'dan gelen gerçek veriyi göreceksin.
Parametreleri Gör: API'nın hangi alanları (isim, yazar vb.) zorunlu tuttuğunu ve veri tiplerini şematik olarak incele.

4. Kod İçinde Dökümantasyonu Özelleştirme

Bazen Swagger'a özel notlar eklemek istersin. Bunun için views.py içinde küçük dokunuşlar yapabiliriz:

Python:
from drf_spectacular.utils import extend_schema

@extend_schema(summary="Tüm kitapları listeler", description="Veritabanındaki tüm kitapları JSON olarak döner.")
class KitapListCreate(generics.ListCreateAPIView):
    # ... kodun devamı ...

🎉 Tebrikler!

Artık profesyonel standartlarda bir API'ın var. Süreci özetlersek:

Model: Veriyi tasarladın.
Serializer: Veriyi JSON'a çevirdin.
Views/URLs: Kapıları açtın.
Token Auth: Güvenliği sağladın.
Swagger: Kullanma kılavuzunu hazırladın.

API'nı profesyonel bir seviyeye taşımanın en önemli adımlarından birine geldik. Veritabanında binlerce kitap olduğunda, hepsini aynı anda çekmek hem performansı düşürür hem de kullanıcı deneyimini bozar.

Kullanıcının şu tarz istekler yapabilmesini sağlayacağız:

?search=Dostoyevski (Arama)
?yazar=Sabahattin Ali (Filtreleme)
?ordering=-eklenme_tarihi (Sıralama)

1. Gerekli Kütüphanenin Kurulumu

Django'nun kendi filtreleme yapısı olsa da, API dünyasında standart haline gelmiş olan django-filter kütüphanesini kullanacağız.

Bash:
pip install django-filter

Ardından core/settings.py dosyasındaki INSTALLED_APPS listesine ekle:

Python:
INSTALLED_APPS = [
    ...
    'django_filters', 
    ...
]

Ayrıca DRF'e bu filtreleme yapısını kullanacağını söylemek için REST_FRAMEWORK ayarlarına şu satırı ekle:

Python:
REST_FRAMEWORK = {
    ...
    'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend'],
}

2. Views İçinde Filtreleme, Arama ve Sıralama

Şimdi api/views.py dosyamıza gidip KitapListCreate sınıfımızı güncelleyelim. DRF bize bu özellikleri "Backend" sınıfları olarak sunar.

Python:
from rest_framework import generics, filters # filters eklendi
from django_filters.rest_framework import DjangoFilterBackend
from .models import Kitap
from .serializers import KitapSerializer

class KitapListCreate(generics.ListCreateAPIView):
    queryset = Kitap.objects.all()
    serializer_class = KitapSerializer
    
    # Kullanacağımız filtreleme yöntemlerini tanımlıyoruz
    filter_backends = [DjangoFilterBackend, filters.SearchFilter, filters.OrderingFilter]
    
    # Birebir eşleşme için filtre alanları
    filterset_fields = ['yazar']
    
    # Metin tabanlı arama yapılacak alanlar
    search_fields = ['isim', 'yazar']
    
    # Sıralama yapılabilecek alanlar
    ordering_fields = ['eklenme_tarihi', 'isim']
    # Varsayılan sıralama (yeni eklenen en üstte)
    ordering = ['-eklenme_tarihi'] 

3. Swagger Üzerinde Test Etme

Sunucuyu çalıştırıp Swagger dökümantasyonuna (/api/docs/) gittiğinde, GET /api/kitaplar/ endpoint'inin yanında yeni butonlar göreceksin.

Artık şu sorguları tarayıcıdan test edebilirsin:

Sadece Belirli Yazarı Getir:
http://127.0.0.1:8000/api/kitaplar/?yazar=George Orwell
Kitap İsmi veya Yazarda Kelime Ara:
http://127.0.0.1:8000/api/kitaplar/?search=Şeker Portakalı
İsme Göre Alfabetik Sırala:
http://127.0.0.1:8000/api/kitaplar/?ordering=isim

4. Bonus: Sayfalama (Pagination)

Eğer 10.000 kitabın varsa, API hala hepsini tek seferde döndürmeye çalışacaktır. Bunu engellemek için settings.py dosyasına basit bir sayfalama kuralı ekleyelim:

Python:
REST_FRAMEWORK = {
    ...
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10 # Her sayfada 10 kayıt göster
}

Yol Haritasında Neredeyiz?

Seninle birlikte "Kurumsal Düzeyde Bir API" mimarisini tamamladık. Şu an elinde;

Güvenli (Token),
Kendi kendini dökümante eden (Swagger),
Hızlı arama ve filtreleme yapabilen,
Düzenli (Sayfalamalı) bir sistem var.