REST API Nedir? Derinlemesine İnceleme ve Uygulama Rehberi

## REST API Mimarisi ve Temel Prensipleri **REST API** (Representational State Transfer), modern web mimarisinin temel taşlarından biridir. Roy Fielding tarafından 2000 yılında doktora tezinde tanımlanan bu mimari stil, istemci ve sunucu arasındaki etkileşimi standartlaştırmayı hedefler. REST, bir protokol değil, bir mimari kısıtlamalar bütünüdür. Bu kısıtlamalara uyan sistemler **RESTful** olarak adlandırılır. REST mimarisinin temelini oluşturan altı ana kısıtlama şunlardır: 1. **Client-Server (İstemci-Sunucu):** İstemci ve sunucu birbirinden tamamen bağımsız olmalıdır. Sunucu veri depolama ve işleme ile ilgilenirken, istemci kullanıcı arayüzü ve deneyimiyle ilgilenir. 2. **Statelessness (Durumsuzluk):** Her istek (request), sunucunun o isteği anlaması için gerekli tüm bilgileri içermelidir. Sunucu, istemci oturumuyla ilgili hiçbir bilgiyi (session) hafızasında tutmaz. 3. **Cacheability (Önbelleklenebilirlik):** Yanıtlar, kendilerini önbelleklenebilir veya önbelleklenemez olarak tanımlamalıdır. Bu, ağ verimliliğini artırır. 4. **Uniform Interface (Tek Tip Arayüz):** Kaynaklara erişim şekli standart olmalıdır (URI kullanımı, HTTP metodları). 5. **Layered System (Katmanlı Sistem):** İstemci, doğrudan son sunucuya mı yoksa bir ara sunucuya mı (proxy, load balancer) bağlı olduğunu bilmemelidir. 6. **Code on Demand (Opsiyonel):** Sunucu, istemciye çalıştırılabilir kod (JavaScript gibi) gönderebilir. ## HTTP Metodları ve Semantik Kullanımı REST API tasarımında kaynaklar üzerinde işlem yapmak için standart HTTP metodları kullanılır. Her metodun belirli bir semantik anlamı vardır. | Metod | İşlem | İdempotent mi? | Açıklama | | :--- | :--- | :--- | :--- | | **GET** | Okuma | Evet | Belirtilen kaynağı getirir. | | **POST** | Oluşturma | Hayır | Yeni bir kaynak oluşturur. | | **PUT** | Güncelleme | Evet | Kaynağı tamamen değiştirir. | | **PATCH** | Kısmi Güncelleme | Hayır | Kaynağın belirli alanlarını günceller. | | **DELETE** | Silme | Evet | Belirtilen kaynağı siler. | ### Pratik Örnek: Express.js ile Temel Rotalar ```javascript const express = require('express'); const app = express(); app.use(express.json()); // GET: Tüm kullanıcıları listele app.get('/api/v1/users', (req, res) => { res.status(200).json({ status: 'success', data: [] }); }); // POST: Yeni kullanıcı oluştur app.post('/api/v1/users', (req, res) => { const newUser = req.body; res.status(201).json({ status: 'created', data: newUser }); }); ``` ## Kaynak Tasarımı ve URI Yapılandırması REST mimarisinde her şey bir **kaynaktır** (resource). Kaynaklar, benzersiz bir URI (Uniform Resource Identifier) ile tanımlanır. URI tasarımı yapılırken isim soylu kelimeler kullanılmalı, fiillerden kaçınılmalıdır. - **Yanlış:** `/getUserDetails/123` veya `/deleteUser/123` - **Doğru:** `/users/123` (GET ile okuma, DELETE ile silme yapılır) > **Not:** Kaynak isimleri her zaman çoğul olmalıdır. `/user/123` yerine `/users/123` kullanımı endüstri standardıdır. ### İç İçe Kaynak Yapısı Bir kaynağın başka bir kaynağa bağımlı olduğu durumlarda hiyerarşik yapı kullanılır: ```http GET /users/123/orders ``` Bu istek, 123 ID'li kullanıcıya ait siparişleri listeler. ## Durum Kodları (Status Codes) ve Hata Yönetimi API yanıtları, işlemin sonucunu belirten standart HTTP durum kodlarını içermelidir. Bu, istemcinin gelen veriyi nasıl işlemesi gerektiğini anlamasını sağlar. - **2xx (Başarı):** 200 OK, 201 Created, 204 No Content. - **4xx (İstemci Hatası):** 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found. - **5xx (Sunucu Hatası):** 500 Internal Server Error, 502 Bad Gateway. ### Hata Yanıtı Standardı Örneği ```json { "error": { "code": 404, "message": "Kullanıcı bulunamadı", "details": "Belirtilen ID ile eşleşen bir kayıt sistemde mevcut değil." } } ``` ## Kimlik Doğrulama ve Güvenlik (OAuth2 & JWT) REST API'ler durumsuz (stateless) olduğu için her istekte kimlik doğrulanmalıdır. En yaygın yöntem **JSON Web Token (JWT)** kullanımıdır. ### JWT Doğrulama Middleware Örneği ```javascript const jwt = require('jsonwebtoken'); const authenticateToken = (req, res, next) => { const authHeader = req.headers['authorization']; const token = authHeader && authHeader.split(' ')[1]; if (!token) return res.sendStatus(401); jwt.verify(token, process.env.ACCESS_TOKEN_SECRET, (err, user) => { if (err) return res.sendStatus(403); req.user = user; next(); }); }; ``` ## Veri Formatları: JSON ve Verimlilik REST API'lerde veri değişimi için en popüler format **JSON**'dır. XML'e göre daha hafif ve parse edilmesi daha kolaydır. Verimlilik için gereksiz veri gönderiminden kaçınılmalıdır. ### JSON Yanıt Örneği ```json { "id": "uuid-12345", "username": "devops_expert", "email": "admin@example.com", "roles": ["admin", "editor"] } ``` ## Sayfalama, Filtreleme ve Sıralama Teknikleri Büyük veri setlerini dönerken performansı korumak için sayfalama (pagination) zorunludur. Query parametreleri bu işlemler için idealdir. ```http GET /api/v1/products?page=2&limit=50&sort=-price&category=electronics ``` ### Sayfalama Mantığı (Node.js) ```javascript app.get('/api/v1/products', async (req, res) => { const { page = 1, limit = 10 } = req.query; const offset = (page - 1) * limit; const products = await Product.find().skip(offset).limit(Number(limit)); res.json({ page, limit, data: products }); }); ``` ## API Sürümleme Stratejileri API'nizde geriye dönük uyumluluğu bozacak değişiklikler yaptığınızda sürümleme (versioning) yapmalısınız. En yaygın yöntem URI sürümlemedir. - **URI Versioning:** `/api/v1/users` - **Header Versioning:** `Accept-version: v1` ## Performans Optimizasyonu ve Önbellekleme API performansını artırmak için `ETag` ve `Cache-Control` başlıkları kullanılmalıdır. Ayrıca veritabanı seviyesinde indeksleme ve Redis gibi in-memory cache çözümleri entegre edilmelidir. ```javascript // Redis ile basit bir cache örneği const getCachedData = async (key) => { const cachedValue = await redisClient.get(key); if (cachedValue) return JSON.parse(cachedValue); const freshData = await fetchDataFromDB(); await redisClient.setEx(key, 3600, JSON.stringify(freshData)); return freshData; }; ``` ## DevOps Süreçlerinde REST API ve Test Otomasyonu DevOps döngüsünde API testleri kritik öneme sahiptir. **CI/CD** süreçlerine entegre edilen otomatik testler, her deployment öncesi API bütünlüğünü korur. ### Supertest ile API Testi Örneği ```javascript const request = require('supertest'); const app = require('../app'); describe('GET /users', () => { it('should return 200 and a list of users', async () => { const res = await request(app).get('/api/v1/users'); expect(res.statusCode).toEqual(200); expect(Array.isArray(res.body.data)).toBe(true); }); }); ``` ## Sık Yapılan Hatalar ve Kaçınılması Gerekenler 1. **Yanlış Durum Kodları:** Her hataya 200 OK dönüp JSON içinde hata mesajı vermek. 2. **Güvensiz Endpointler:** Kimlik doğrulaması gerektiren işlemleri açık bırakmak. 3. **Dökümantasyon Eksikliği:** API'nin nasıl kullanılacağına dair Swagger/OpenAPI dökümanı sağlamamak. 4. **Aşırı Veri Gönderimi:** İstemcinin ihtiyacı olmayan tüm veritabanı kolonlarını dönmek. ## Geleceğe Bakış: REST vs GraphQL ve gRPC REST hala endüstri standardı olsa da, **GraphQL** (esnek veri çekme) ve **gRPC** (yüksek performanslı mikroservis iletişimi) gibi alternatifler popülerlik kazanmaktadır. Ancak REST'in basitliği ve evrenselliği onu birçok proje için hala en güvenli liman yapmaktadır. ### OpenAPI/Swagger Örneği ```yaml openapi: 3.0.0 info: title: User API version: 1.0.0 paths: /users: get: summary: Tüm kullanıcıları getirir responses: '200': description: Başarılı liste ``` ## Sık Sorulan Sorular (FAQ) 1. **REST ve SOAP arasındaki fark nedir?** REST bir mimari stildir ve JSON/XML kullanabilir; SOAP bir protokoldür ve sadece XML kullanır. REST daha hafif ve hızlıdır. 2. **Idempotent ne demektir?** Bir işlemin defalarca yapılmasına rağmen sonucun değişmemesidir (Örn: GET, PUT, DELETE). 3. **PATCH ve PUT arasındaki fark nedir?** PUT kaynağı tamamen değiştirirken, PATCH sadece belirtilen alanları günceller. 4. **HATEOAS nedir?** İstemcinin API yanıtı içindeki linkler aracılığıyla diğer kaynakları keşfetmesini sağlayan bir REST kısıtlamasıdır. 5. **API güvenliği için en önemli adım nedir?** HTTPS kullanımı ve güçlü bir kimlik doğrulama (JWT/OAuth2) mekanizması kurulmasıdır. ## Özet ve Sonuç REST API, ölçeklenebilir ve esnek web servisleri geliştirmenin en etkili yoludur. Doğru HTTP metodları, anlamlı URI yapıları ve standart durum kodları kullanarak hem geliştirici dostu hem de performanslı sistemler inşa edebilirsiniz. DevOps süreçlerinde otomasyon ve testlerle desteklenen bir RESTful mimari, modern yazılım geliştirme dünyasında başarının anahtarıdır.