API Tasarımı Best Practices: RESTful API ve En İyi Uygulamalar

RESTful API Temelleri

REST (Representational State Transfer), web servisleri tasarlamak için kullanılan bir mimari stildir. HTTP protokolünün metodlarını (GET, POST, PUT, DELETE) kullanır.

Kaynak (Resource): API'nin temel yapı taşıdır. Her kaynak benzersiz bir URI ile tanımlanır: /users, /users/123, /users/123/orders.

HTTP metodları: GET (okuma), POST (oluşturma), PUT (tam güncelleme), PATCH (kısmi güncelleme), DELETE (silme). Her metod, kaynağa yönelik bir işlemi temsil eder.

Durumsuzluk (Stateless): Her istek, gerekli tüm bilgiyi içermelidir. Sunucu, istemci durumunu saklamaz. Bu, ölçeklenebilirliği artırır.

HATEOAS: Hypermedia as the Engine of Application State. API yanıtları, ilgili kaynaklara linkler içerir. Bu, API'nin kendi kendini dokümante etmesini sağlar.

Endpoint Tasarımı

İsimlendirme: Çoğul isimler kullanın: /users, /products, /orders. Tekil isimlerden kaçının: /user, /product.

İç içe kaynaklar: /users/123/orders ile kullanıcının siparişlerini alın. 3 seviyeden fazla iç içe yapıdan kaçının.

Filtreleme ve sıralama: Query parametreleri kullanın: /products?category=electronics&sort=price&order=asc.

Sayfalama: Offset-based (/products?page=2&limit=20) veya cursor-based (/products?cursor=abc123&limit=20). Büyük veri setleri için cursor-based daha verimlidir.

Versiyonlama: URL'de versiyon belirtin: /api/v1/users. Breaking change'lerde yeni versiyon oluşturun. Eski versiyonları belirli bir süre destekleyin.

Hata Yönetimi

HTTP status kodları: 200 (OK), 201 (Created), 204 (No Content), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 422 (Unprocessable Entity), 500 (Internal Server Error).

Hata yanıtı formatı: { "error": { "code": "VALIDATION_ERROR", "message": "Email is required", "details": [{ "field": "email", "message": "This field is required" }] } }.

Tutarlılık: Tüm hata yanıtları aynı formatı kullanmalıdır. Hata kodları (string) ile programatik hata yönetimi sağlayın.

Rate limiting: 429 (Too Many Requests) status kodu ile rate limit aşımını bildirin. Retry-After header'ı ile ne zaman tekrar deneneceğini belirtin.

Logging: Tüm hataları sunucu tarafında loglayın. Correlation ID (request-id) ile istek takibi sağlayın.

Güvenlik Best Practices

Authentication: JWT (JSON Web Token) veya OAuth 2.0 kullanın. API key'leri sadece server-to-server iletişimde kullanın.

Authorization: Role-based access control (RBAC) veya attribute-based access control (ABAC) ile yetkilendirme yapın.

HTTPS: Tüm API trafiği HTTPS üzerinden olmalıdır. HTTP isteklerini HTTPS'ye yönlendirin.

Input validation: Tüm girdileri sunucu tarafında doğrulayın. SQL injection, XSS ve CSRF saldırılarına karşı koruma sağlayın.

CORS: Cross-Origin Resource Sharing ayarlarını doğru yapılandırın. Sadece güvenilir origin'lere izin verin.

Rate limiting: IP veya kullanıcı bazlı rate limiting uygulayın. Brute force ve DDoS saldırılarını önleyin.

Performans ve Önbellekleme

Pagination: Büyük veri setlerini sayfalayın. Limit ve offset parametreleri kullanın.

Field selection: Sadece gerekli alanları döndürün: /users?fields=id,name,email. Bu, response boyutunu azaltır.

Compression: Gzip veya Brotli sıkıştırma ile response boyutunu %60-80 azaltın.

Caching: GET istekleri için HTTP cache header'ları (Cache-Control, ETag) kullanın. CDN ile API yanıtlarını önbellekleyin.

GraphQL: Karmaşık veri gereksinimleri için REST yerine GraphQL düşünün. Over-fetching ve under-fetching sorunlarını çözer.

Dokümantasyon

OpenAPI (Swagger): API dokümantasyonunu OpenAPI spec ile tanımlayın. Swagger UI ile interaktif dokümantasyon oluşturun.

Postman Collection: API endpoint'lerini Postman collection olarak paylaşın. Test ve dokümantasyon için kullanılır.

Code examples: Her endpoint için curl, JavaScript, Python gibi dillerde kod örnekleri ekleyin.

Changelog: API değişikliklerini changelog'da dokümante edin. Breaking change'leri açıkça belirtin.

Rate limits ve quotas: API limitlerini ve kotalarını dokümantasyonda belirtin. Kullanıcıların limitleri aşmasını önleyin.