REST, Representational State Transfer’ın kısaltmasıdır. Web servisleri oluştururken kullanılan bir mimari tarzdır ve HTTP protokolü üzerine kuruludur. RESTful API’ler, kaynakları (veri nesneleri) URI’ler aracılığıyla tanımlar ve bu kaynaklar üzerinde CRUD (Create, Read, Update, Delete) işlemlerini standart HTTP metotlarıyla gerçekleştirir.
Kaynaklar ve URI Tasarımı
REST’te her nesne bir kaynaktır ve URI’ler bu kaynakları tanımlar. İyi tasarlanmış URI’ler okunabilir, tutarlı ve hiyerarşik olmalıdır. Örneğin, /users/123 tek bir kullanıcıyı, /users/123/posts ise kullanıcının tüm gönderilerini temsil eder. URI’ler tekil isimler kullanmalı ve çoğul isimlerden kaçınılmalıdır. Ayrıca, kaynaklar için mantıklı alt diziler oluşturmak, API’nin ölçeklenebilirliğini artırır.
HTTP Metotları ve Durum Kodları
RESTful API’lerde standart HTTP metotları şu şekildedir:
- GET – Kaynakları okuma
- POST – Yeni kaynak oluşturma
- PUT – Kaynağı güncelleme (tam değişim)
- PATCH – Kaynağın kısmi güncellenmesi
- DELETE – Kaynağı silme
İşlemlerin sonucunu ifade eden HTTP durum kodları da önemlidir. Başarılı bir GET isteği 200 OK, yeni kaynak oluşturma 201 Created, kaynak bulunamazsa 404 Not Found, yetkilendirme hatası 401 Unauthorized gibi kodlar kullanılır.
JSON ve XML Formatları
Veri alışverişi için JSON, XML ve bazen YAML tercih edilir. JSON, hafif yapısı ve JavaScript ile uyumu sayesinde en popüler formattır. API’yi tasarlarken Content-Type ve Accept başlıklarını doğru ayarlamak, istemcinin hangi formatta veri göndereceğini ve alacağını netleştirir. Örnek bir JSON yanıtı:
{
"id": 123,
"name": "Ahmet",
"email": "ahmet@example.com"
}
Hata Yönetimi
Hatalar, API’nin kullanıcı dostu olmasını sağlar. Hata mesajları, error alanı ile birlikte anlaşılır bir açıklama içermelidir. Örnek bir hata yanıtı:
{
"error": "User not found",
"code": 404
}
Bu yapı, istemcinin hatayı programatik olarak işlemesini kolaylaştırır.
Güvenlik Önlemleri
RESTful API’ler genellikle açık ağlarda çalışır, bu nedenle güvenlik kritik bir konudur. OAuth 2.0 veya JWT token’ları, yetkilendirme için tercih edilen yöntemlerdir. Ayrıca, HTTPS zorunlu kılınmalı, Rate Limiting ile brute-force saldırıları engellenmeli ve Input Validation ile SQL injection gibi saldırılara karşı önlem alınmalıdır.
Versiyonlama
API’yi güncellerken geriye dönük uyumluluğu korumak gerekir. URI içinde /v1/ gibi bir sürüm numarası eklemek en yaygın yaklaşımdır. Alternatif olarak, Accept başlığıyla içerik türü ve sürümü belirten bir application/vnd.myapi.v1+json kullanmak da mümkündür.
Performans Optimizasyonu
API performansını artırmak için Cache mekanizmaları, ETag ve If-None-Match başlıkları kullanılabilir. Ayrıca, Pagination ile büyük veri setlerini bölmek, istemcinin yükünü hafifletir. Örneğin, ?page=2&limit=50 gibi parametreler kullanılır.
Test ve Dokümantasyon
API’yi geliştirdikten sonra Unit, Integration ve Contract testleri ile güvenilirliği sağlanır. OpenAPI (Swagger) gibi araçlar, otomatik dokümantasyon ve istemci kütüphaneleri üretir. İyi bir dokümantasyon, API’nin benimsenmesini hızlandırır.
Sonuç
RESTful API yazarken, kaynak odaklı tasarım, standart HTTP metotları ve tutarlı URI’ler temel oluşturur. Güvenlik, versiyonlama, performans ve dokümantasyon, API’nin sürdürülebilirliği için kritik unsurlardır. Bu prensipleri takip ederek, ölçeklenebilir, bakımı kolay ve kullanıcı dostu bir web servisi geliştirebilirsiniz.