Node.js ve Express.js ile REST API Geliştirme: Kapsamlı Rehber

Başlangıç ve Orta Seviye Geliştiriciler için Pratik REST API Rehberi

Nov 05, 2025

Giriş

Modern web uygulamalarının omurgasını oluşturan REST API’ler, frontend ve backend arasındaki iletişimi sağlayan kritik bileşenlerdir. Bu makalede, Node.js ve Express.js kullanarak profesyonel bir REST API nasıl geliştirileceğini, gerçek dünya örnekleriyle adım adım inceleyeceğiz.

Proje Kurulumu

Öncelikle yeni bir Node.js projesi oluşturalım:

mkdir express-api-example
cd express-api-example
npm init -y

Gerekli paketleri yükleyelim:

npm install express dotenv cors helmet morgan
npm install --save-dev nodemon

Paket Açıklamaları:

express: Web framework
dotenv: Ortam değişkenlerini yönetmek için
cors: Cross-Origin Resource Sharing
helmet: Güvenlik için HTTP header’ları ayarlar
morgan: HTTP istek logger’ı
nodemon: Geliştirme sırasında otomatik yeniden başlatma

Proje Yapısı

express-api-example/
├── src/
│   ├── config/
│   │   └── database.js
│   ├── controllers/
│   │   └── userController.js
│   ├── middleware/
│   │   ├── auth.js
│   │   └── errorHandler.js
│   ├── models/
│   │   └── userModel.js
│   ├── routes/
│   │   └── userRoutes.js
│   ├── utils/
│   │   └── validators.js
│   └── app.js
├── .env
├── .gitignore
├── package.json
└── server.js

Temel Yapılandırma

1. Environment Variables (.env)

PORT=3000
NODE_ENV=development
API_VERSION=v1

2. Ana Uygulama Dosyası (src/app.js)

const express = require(’express’);
const cors = require(’cors’);
const helmet = require(’helmet’);
const morgan = require(’morgan’);
require(’dotenv’).config();

const userRoutes = require(’./routes/userRoutes’);
const errorHandler = require(’./middleware/errorHandler’);

const app = express();

// Middleware’ler
app.use(helmet()); // Güvenlik başlıkları
app.use(cors()); // CORS yapılandırması
app.use(morgan(’dev’)); // İstek logları
app.use(express.json()); // JSON body parser
app.use(express.urlencoded({ extended: true })); // URL-encoded body parser

// Ana route
app.get(’/’, (req, res) => {
  res.json({
    message: ‘Express API çalışıyor!’,
    version: process.env.API_VERSION,
    timestamp: new Date().toISOString()
  });
});

// API Routes
app.use(`/api/${process.env.API_VERSION}/users`, userRoutes);

// 404 Handler
app.use((req, res) => {
  res.status(404).json({
    success: false,
    message: ‘Endpoint bulunamadı’
  });
});

// Error Handler
app.use(errorHandler);

module.exports = app;

3. Server Başlatıcı (server.js)

const app = require(’./src/app’);

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(`🚀 Server ${PORT} portunda çalışıyor`);
  console.log(`📝 Environment: ${process.env.NODE_ENV}`);
  console.log(`🔗 URL: http://localhost:${PORT}`);
});

Model Katmanı

User Model (src/models/userModel.js)

// Basit bir in-memory veritabanı simülasyonu
let users = [
  { id: 1, name: ‘Ahmet Yılmaz’, email: ‘ahmet@example.com’, age: 28 },
  { id: 2, name: ‘Ayşe Demir’, email: ‘ayse@example.com’, age: 32 }
];

let nextId = 3;

class UserModel {
  static getAll() {
    return users;
  }

  static getById(id) {
    return users.find(user => user.id === parseInt(id));
  }

  static create(userData) {
    const newUser = {
      id: nextId++,
      ...userData,
      createdAt: new Date().toISOString()
    };
    users.push(newUser);
    return newUser;
  }

  static update(id, userData) {
    const index = users.findIndex(user => user.id === parseInt(id));
    if (index === -1) return null;

    users[index] = {
      ...users[index],
      ...userData,
      updatedAt: new Date().toISOString()
    };
    return users[index];
  }

  static delete(id) {
    const index = users.findIndex(user => user.id === parseInt(id));
    if (index === -1) return false;

    users.splice(index, 1);
    return true;
  }

  static search(query) {
    return users.filter(user =>
      user.name.toLowerCase().includes(query.toLowerCase()) ||
      user.email.toLowerCase().includes(query.toLowerCase())
    );
  }
}

module.exports = UserModel;

Controller Katmanı

User Controller (src/controllers/userController.js)

const UserModel = require(’../models/userModel’);
const { validateUser } = require(’../utils/validators’);

class UserController {
  // Tüm kullanıcıları getir
  static async getAllUsers(req, res, next) {
    try {
      const { search } = req.query;
      
      let users;
      if (search) {
        users = UserModel.search(search);
      } else {
        users = UserModel.getAll();
      }

      res.json({
        success: true,
        count: users.length,
        data: users
      });
    } catch (error) {
      next(error);
    }
  }

  // ID ile kullanıcı getir
  static async getUserById(req, res, next) {
    try {
      const user = UserModel.getById(req.params.id);

      if (!user) {
        return res.status(404).json({
          success: false,
          message: ‘Kullanıcı bulunamadı’
        });
      }

      res.json({
        success: true,
        data: user
      });
    } catch (error) {
      next(error);
    }
  }

  // Yeni kullanıcı oluştur
  static async createUser(req, res, next) {
    try {
      const { error } = validateUser(req.body);
      if (error) {
        return res.status(400).json({
          success: false,
          message: error
        });
      }

      const newUser = UserModel.create(req.body);

      res.status(201).json({
        success: true,
        message: ‘Kullanıcı başarıyla oluşturuldu’,
        data: newUser
      });
    } catch (error) {
      next(error);
    }
  }

  // Kullanıcı güncelle
  static async updateUser(req, res, next) {
    try {
      const { error } = validateUser(req.body, true);
      if (error) {
        return res.status(400).json({
          success: false,
          message: error
        });
      }

      const updatedUser = UserModel.update(req.params.id, req.body);

      if (!updatedUser) {
        return res.status(404).json({
          success: false,
          message: ‘Kullanıcı bulunamadı’
        });
      }

      res.json({
        success: true,
        message: ‘Kullanıcı başarıyla güncellendi’,
        data: updatedUser
      });
    } catch (error) {
      next(error);
    }
  }

  // Kullanıcı sil
  static async deleteUser(req, res, next) {
    try {
      const deleted = UserModel.delete(req.params.id);

      if (!deleted) {
        return res.status(404).json({
          success: false,
          message: ‘Kullanıcı bulunamadı’
        });
      }

      res.json({
        success: true,
        message: ‘Kullanıcı başarıyla silindi’
      });
    } catch (error) {
      next(error);
    }
  }
}

module.exports = UserController;

Middleware

Error Handler (src/middleware/errorHandler.js)

const errorHandler = (err, req, res, next) => {
  console.error(’❌ Hata:’, err);

  const statusCode = err.statusCode || 500;
  const message = err.message || ‘Sunucu hatası’;

  res.status(statusCode).json({
    success: false,
    message: message,
    ...(process.env.NODE_ENV === ‘development’ && { stack: err.stack })
  });
};

module.exports = errorHandler;

Auth Middleware (src/middleware/auth.js)

const auth = (req, res, next) => {
  const token = req.headers.authorization?.split(’ ‘)[1];

  if (!token) {
    return res.status(401).json({
      success: false,
      message: ‘Yetkilendirme token\’ı gerekli’
    });
  }

  // Basit token kontrolü (gerçek uygulamada JWT kullanılır)
  if (token !== ‘demo-token-123’) {
    return res.status(403).json({
      success: false,
      message: ‘Geçersiz token’
    });
  }

  next();
};

module.exports = auth;

Validators

Validation Utilities (src/utils/validators.js)

const validateUser = (data, isUpdate = false) => {
  const { name, email, age } = data;

  if (!isUpdate) {
    if (!name || typeof name !== ‘string’ || name.trim().length < 2) {
      return { error: ‘Geçerli bir isim giriniz (min 2 karakter)’ };
    }

    if (!email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
      return { error: ‘Geçerli bir email adresi giriniz’ };
    }
  }

  if (age !== undefined && (typeof age !== ‘number’ || age < 0 || age > 150)) {
    return { error: ‘Yaş 0-150 arasında bir sayı olmalıdır’ };
  }

  return { error: null };
};

module.exports = { validateUser };

Routes

User Routes (src/routes/userRoutes.js)

const express = require(’express’);
const router = express.Router();
const UserController = require(’../controllers/userController’);
const auth = require(’../middleware/auth’);

// Public routes
router.get(’/’, UserController.getAllUsers);
router.get(’/:id’, UserController.getUserById);

// Protected routes (auth middleware ile korumalı)
router.post(’/’, auth, UserController.createUser);
router.put(’/:id’, auth, UserController.updateUser);
router.delete(’/:id’, auth, UserController.deleteUser);

module.exports = router;

Package.json Scripts

{
  “scripts”: {
    “start”: “node server.js”,
    “dev”: “nodemon server.js”,
    “test”: “echo \”Error: no test specified\” && exit 1”
  }
}

API Kullanım Örnekleri

1. Tüm Kullanıcıları Getir

curl http://localhost:3000/api/v1/users

Yanıt:

{
  “success”: true,
  “count”: 2,
  “data”: [
    {
      “id”: 1,
      “name”: “Ahmet Yılmaz”,
      “email”: “ahmet@example.com”,
      “age”: 28
    }
  ]
}

2. Arama ile Kullanıcı Bul

curl http://localhost:3000/api/v1/users?search=ahmet

3. Yeni Kullanıcı Oluştur

curl -X POST http://localhost:3000/api/v1/users \
  -H “Content-Type: application/json” \
  -H “Authorization: Bearer demo-token-123” \
  -d ‘{
    “name”: “Mehmet Kaya”,
    “email”: “mehmet@example.com”,
    “age”: 25
  }’

4. Kullanıcı Güncelle

curl -X PUT http://localhost:3000/api/v1/users/1 \
  -H “Content-Type: application/json” \
  -H “Authorization: Bearer demo-token-123” \
  -d ‘{
    “age”: 29
  }’

5. Kullanıcı Sil

curl -X DELETE http://localhost:3000/api/v1/users/1 \
  -H “Authorization: Bearer demo-token-123”

Sonuç

Bu makalede Node.js ve Express.js ile profesyonel bir REST API geliştirmeyi öğrendik. Örneğimiz şunları içeriyor:

✅ Katmanlı mimari (MVC)
✅ Middleware kullanımı
✅ Error handling
✅ Validation
✅ Authentication
✅ Clean code prensipleri

Bu temel yapıyı kullanarak MongoDB, PostgreSQL gibi gerçek veritabanları, JWT authentication, file upload, websocket gibi gelişmiş özellikler ekleyebilirsiniz.

Öğrenirken Aldığım Notlar

Discussion about this post

Ready for more?