Modern istemci-sunucu (Client-Server) mimarilerinde API'ler, tüm sistemin omurgasını oluşturur. Bir Web API'sinin esnek, anlaşılır ve güvenli tasarlanması; frontend geliştiricilerinin işini kolaylaştırdığı gibi sistemin ölçeklenebilirliğini de doğrudan etkiler.
İyi bir API tasarımı, sadece veri taşıyan bir köprü değil; geliştirici deneyimini (Developer Experience - DX) en üst düzeye çıkaran bir sözleşmedir (contract).
1. RESTful API Tasarım İlkeleri
REST mimarisi kullanırken kaynak odaklı (Resource-Oriented) bir yaklaşım benimsemek esastır.
- İsim Soyutlaması (Nouns over Verbs): Endpoint isimlerinde fiil yerine çoğul isimler tercih edilmelidir (
/getUserListveya/deleteUseryerine GET/DELETE/api/v1/users). - Doğru HTTP Metotları: Eylemleri URL'e yazmak yerine HTTP metotları (GET, POST, PUT, PATCH, DELETE) ile ifade edin.
- Tutarlı Hata ve Yanıt Formatı: Tüm API yanıtlarında (başarılı veya hatalı) standart bir JSON gövdesi dönün.
2. HTTP Durum Kodlarının (Status Codes) Doğru Kullanımı
İstemciye dönen HTTP durum kodu, hatanın veya başarının doğasını anında açıklamalıdır.
| Durum Kodu | Anlamı | Kullanım Senaryosu |
|---|---|---|
| 200 OK | Başarılı | Veri başarıyla getirildi veya güncellendi. |
| 201 Created | Oluşturuldu | Yeni bir kaynak (Resource) başarıyla eklendi. |
| 400 Bad Request | Geçersiz İstek | İstemci eksik veya hatalı veri gönderdi (Validation hatası). |
| 401 Unauthorized | Yetkisiz | Kimlik doğrulaması yapılmamış (JWT token eksik/geçersiz). |
| 403 Forbidden | Yasaklı | İstemci kimliğini kanıtlamış ancak bu kaynağa erişim yetkisi yok. |
| 404 Not Found | Bulunamadı | İstenen kaynak veritabanında mevcut değil. |
3. Örnek API Endpoint Katmanı
Express ve TypeScript ile yazılmış temiz bir Controller örneği:
typescript
import { Request, Response } from 'express';
interface CreateUserDTO { email: string; name: string; }
// POST /api/v1/users export async function createUser(req: Request, res: Response): Promise { const { email, name }: CreateUserDTO = req.body;
if (!email || !name) { return res.status(400).json({ success: false, error: 'BAD_REQUEST', message: 'Email and name are required fields.' }); }
const newUser = await UserService.create({ email, name });
return res.status(201).json({ success: true, data: newUser }); }
- Güvenlik, Performans ve Versiyonlama Pagination (Sayfalama): Büyük veri kümesini tek seferde dönmek sunucuyu kilitler. GET /api/v1/products?page=1&limit=20 yapısını standartlaştırın.
Rate Limiting: IP veya kullanıcı bazlı istek sınırlaması ekleyerek Brute Force ve DDoS saldırı risklerini azaltın.
Versiyonlama: API değişikliklerinin mevcut istemcileri bozmaması için URI versiyonlama (/v1/, /v2/) uygulayın.
Sonuç
İyi tasarlanmış bir API, dokümantasyona ihtiyaç duymayacak kadar sezgisel olmalıdır. Anlaşılır durum kodları, tutarlı yanıt şemaları ve doğru güvenlik önlemleriyle inşa edilen servisler, uzun vadede bakımı en kolay sistemlerdir.