Node.js İle Restful Api Tasarımı Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Geliştirme ortamınızı hazırlamak için bilgisayarınızda Node.js'in en güncel LTS (Long Term Support) sürümünün yüklü olması gerekir. Terminalinizi açarak node -v komutu ile sürüm kontrolü yapabilirsiniz.

• Node.js (v22 veya üzeri önerilir)
• npm veya pnpm paket yöneticisi
• Postman veya Insomnia (API testleri için)
• VS Code veya tercih ettiğiniz bir kod editörü

Projenizi başlatmak için bir klasör oluşturun ve terminalde şu komutları çalıştırın:

mkdir node-api-projem
cd node-api-projem
npm init -y
npm install express dotenv cors helmet

Burada express web çatısını, dotenv çevre değişkenlerini yönetmek için, cors çapraz kaynak erişimini düzenlemek için ve helmet ise HTTP başlıklarını güvenli hale getirmek için yüklüyoruz.

Temel Express.js Sunucusunu Kurma

API'nizin giriş noktası olan app.js dosyasını oluşturarak temel bir sunucu ayağa kaldıralım. Bu aşamada sunucunun gelen istekleri karşılayıp karşılamadığını kontrol edeceğiz.

const express = require('express');
const helmet = require('helmet');
const app = express();
const PORT = process.env.PORT || 3000;

app.use(helmet()); // Güvenlik başlıklarını ekler
app.use(express.json()); // JSON gövdelerini işler

app.get('/', (req, res) => {
    res.status(200).json({ message: 'API başarıyla çalışıyor.' });
});

app.listen(PORT, () => {
    console.log(`Sunucu http://localhost:${PORT} adresinde çalışıyor.`);
});

Bu kod bloğu, uygulamanızın temel iskeletidir. helmet kullanımı, uygulamanızı bilinen web açıklarına karşı korumak için kritik bir güvenlik katmanıdır.

RESTful API Prensipleri ve HTTP Metotları

REST mimarisinde her kaynak (resource) bir URL ile temsil edilir. HTTP metotları ise bu kaynak üzerinde hangi işlemin yapılacağını belirler. Aşağıdaki tablo, standart bir API tasarımında kullanılan metotları özetler.

Veri Yönetimi ve CRUD Operasyonları

API'nizin gerçek bir veritabanı ile konuşması gerekir. Örnek olarak bir "Ürün" (Product) yönetimi senaryosu üzerinden CRUD işlemlerini inceleyelim. Aşağıdaki kod, bir POST isteği ile veri almayı ve bunu doğrulamayı gösterir.

// Ürün ekleme rotası
app.post('/api/products', (req, res) => {
    const { name, price } = req.body;
    if (!name || !price) {
        return res.status(400).json({ error: 'Eksik veri gönderildi.' });
    }
    // Veritabanı kayıt işlemi buraya gelecek
    res.status(201).json({ message: 'Ürün başarıyla oluşturuldu', data: { name, price } });
});

Burada 400 Bad Request hata kodu, istemcinin hatalı veri gönderdiğini belirtir. 201 Created ise kaynağın başarıyla oluşturulduğunu ifade eden standart bir başarı kodudur.

Güvenlik ve Validasyon Stratejileri

API güvenliği, sadece HTTPS kullanmaktan ibaret değildir. Gelen verilerin doğrulanması (validation) ve yetkilendirme süreçleri hayati önem taşır. Kullanıcı girdilerini doğrulamak için joi veya zod gibi kütüphaneler kullanmanızı öneririm.

Kritik Uyarı: Asla kullanıcıdan gelen veriyi doğrudan veritabanı sorgularına (SQL veya NoSQL) dahil etmeyin. Bu durum SQL Injection veya NoSQL Injection açıklarına yol açar. Her zaman parametreli sorgular veya ORM (Object-Relational Mapping) araçları kullanın.

Şifreleme işlemleri için ise asla düz metin (plain text) saklamayın. bcrypt kütüphanesi ile şifreleri hashleyerek veritabanına kaydedin.

Hata Yönetimi ve Middleware Kullanımı

Uygulamanın beklenmedik bir anda çökmesini engellemek için merkezi bir hata yakalayıcı (Error Handling Middleware) kullanmalısınız. Bu, API'nizin profesyonel görünmesini ve hataların loglanmasını sağlar.

// Hata yakalayıcı middleware
app.use((err, req, res, next) => {
    console.error(err.stack);
    res.status(500).json({ error: 'Sunucuda bir hata oluştu.' });
});

Bu middleware, uygulamanın herhangi bir yerinde oluşan hataları yakalar ve kullanıcıya güvenli bir mesaj döndürür.

Sıkça Sorulan Sorular

Node.js ile API yazarken neden Express.js kullanmalıyım?

Express.js, minimalist yapısı ve geniş middleware ekosistemi sayesinde hızlı bir şekilde API geliştirmenize olanak tanır. Standartları belirlemesi, ekip içi çalışmalarda kodun okunabilirliğini artırır.

API güvenliğini nasıl sağlarım?

Helmet ile HTTP başlıklarını koruyun, CORS ayarlarını kısıtlayın, JWT (JSON Web Token) ile yetkilendirme yapın ve mutlaka rate-limiting (istek sınırlama) uygulayın.

RESTful API ile GraphQL arasındaki fark nedir?

REST, kaynak odaklıdır ve sabit uç noktalar (endpoints) kullanır. GraphQL ise sorgu odaklıdır; istemci, ihtiyacı olan veriyi tam olarak belirterek sunucudan talep eder.

Veritabanı olarak ne kullanmalıyım?

İlişkisel veriler için PostgreSQL, esnek ve döküman tabanlı veriler için MongoDB endüstri standartlarıdır. Node.js ile Prisma veya Mongoose ORM'lerini kullanmak iş süreçlerini hızlandırır.

API dokümantasyonu neden önemlidir?

API'nizi başkalarının (veya gelecekteki kendinizin) kullanabilmesi için Swagger (OpenAPI) gibi araçlarla dokümante etmek, entegrasyon süreçlerini kolaylaştırır.

Yasal Uyarı: Bu rehberdeki kod örnekleri eğitim amaçlıdır. Üretim ortamına (production) çıkmadan önce, güvenlik yamalarını güncellemeli, hassas bilgileri (veritabanı şifreleri vb.) çevre değişkenlerinde (env) saklamalı ve gerekli sızma testlerini yapmalısınız.

API Performansını Optimize Etme ve Ölçeklendirme

API'niz yayına alındıktan sonra artan trafikle birlikte performans sorunları yaşanabilir. Node.js'in olay döngüsü (event loop) yapısını bozmadan, uygulamanızı daha hızlı ve verimli hale getirmek için şu stratejileri uygulayabilirsiniz:

1. Gzip Sıkıştırma Kullanımı

Sunucudan istemciye gönderilen JSON verilerinin boyutunu küçültmek, ağ trafiğini ciddi oranda azaltır. Express.js üzerinde compression middleware'ini kullanarak bu işlemi kolayca yapabilirsiniz.

const compression = require('compression');
const express = require('express');
const app = express();

// Tüm yanıtları sıkıştır
app.use(compression());

app.get('/api/data', (req, res) => {
  res.json({ message: "Bu veri sıkıştırılarak gönderilir." });
});

2. Redis ile Önbellekleme (Caching)

Veritabanı sorguları genellikle API'deki en yavaş kısımlardır. Sıkça erişilen verileri (örneğin; ürün listeleri, kategoriler) Redis gibi bir bellek içi veri deposunda tutarak yanıt sürelerini milisaniyelere indirebilirsiniz.

API Test Süreçleri: Jest ve Supertest

Yazdığınız endpoint'lerin beklenen sonuçları verip vermediğini manuel test etmek yerine, otomatik test senaryoları oluşturmalısınız. Jest ve Supertest ikilisi, Express API'leri için endüstri standardıdır.

Öncelikle gerekli paketleri yükleyin: npm install --save-dev jest supertest

Aşağıdaki örnek, bir GET isteğinin başarıyla 200 durum kodu döndürüp döndürmediğini kontrol eder:

const request = require('supertest');
const app = require('../app'); // Express uygulamanızı import edin

describe('GET /api/users', () => {
  it('Tüm kullanıcıları getirmeli ve 200 dönmeli', async () => {
    const res = await request(app).get('/api/users');
    expect(res.statusCode).toEqual(200);
    expect(res.body).toHaveProperty('users');
  });
});

Deployment ve Sürekli Entegrasyon (CI/CD)

API'nizi yerel ortamdan canlı ortama taşırken dikkat etmeniz gereken en önemli nokta, uygulamanın her zaman ayakta kalmasını sağlamaktır. Bunun için PM2 gibi bir süreç yöneticisi kullanmak şarttır.

• PM2 Kullanımı: Uygulamanız çöktüğünde otomatik olarak yeniden başlatır ve çoklu çekirdek (cluster mode) desteği sunar.
• Çevre Değişkenleri: .env dosyasındaki bilgileri asla git deposuna yüklemeyin. Canlı ortamda bu değişkenleri sunucu panelinden (Heroku, AWS, DigitalOcean) tanımlayın.
• Log Yönetimi: Hataları takip etmek için Winston veya Morgan gibi kütüphanelerle logları bir dosyaya veya merkezi bir log servisine aktarın.

# PM2 ile uygulamayı başlatma
pm2 start server.js -i max --name "rest-api"

# Uygulama durumunu izleme
pm2 monit

İpucu: API'nizi yayına almadan önce helmet kütüphanesini kullanarak HTTP başlıklarını (headers) güvenli hale getirmeyi unutmayın. Bu, uygulamanızı bilinen birçok web saldırısına karşı koruyacaktır.

Sonuç

Node.js ile RESTful API tasarımı yapmak, doğru mimari prensipleri ve güvenlik önlemleriyle birleştiğinde oldukça güçlü sonuçlar verir. Bu eğitimde, temel sunucu kurulumundan güvenlik katmanlarına kadar kritik adımları inceledik. Bir sonraki adımda, JWT (JSON Web Token) kullanarak kullanıcı kimlik doğrulama sistemini (Authentication) projenize entegre etmeyi öğrenmenizi öneririm. Sürekli pratik yapmak ve dokümantasyon okumak, sizi bu alanda kıdemli bir geliştirici seviyesine taşıyacaktır.