Laravel ile Modüler ve Ölçeklenebilir RESTful API Geliştirme Yolculuğu

Selamlar, ben Erhan. Uzun süredir backend geliştirme dünyasında yer alıyorum ve son zamanlarda, ölçeklenebilir ve modüler bir yapıya sahip RESTful API geliştirme konusunda kendimi daha da geliştirmeye üzerine yoğunlaşmış durumdayım... Bugün sizlerle, Laravel kullanarak profesyonelce (olduğu kadarıyla) nasıl bir API inşa ettiğimi ve bu süreçte hangi araçları, yaklaşımları benimsediğimi paylaşacağım. Hem teknik detaylara gireceğim hem de neden bu kararları aldığımı, hangi problemleri çözmeye çalıştığımı anlatacağım. Umarım bu yazı, sizlere de ilham verir!

Projenin Temelleri: Neden Laravel ve Neden Modüler Mimari?

Öncelikle, projemde Laravel’i seçmemin en büyük sebeplerinden biri; Laravel, modern PHP dünyasının en popüler framework’lerinden biri olarak, hızlı geliştirme süreci, zengin ekosistemi ve güçlü topluluğu sayesinde bana büyük avantajlar sağladı. Projemde, özellikle B2B konteyner lojistik pazaryeri gibi dinamik ve çok yönlü bir sistemi hayata geçirmek istiyorum. Bunun için;

Kimlik Doğrulama: Laravel Passport ile OAuth2 tabanlı güvenli bir kimlik doğrulama sistemi kurmayı planladım.
Ödeme İşlemleri: Hem Iyzico hem de Stripe entegrasyonları ile abonelik (aylık/yıllık) ve tek seferlik ödeme seçeneklerini sunmayı hedefliyorum.
Modüler Yapı: Her özelliği (örneğin, kullanıcı yönetimi, ilanlar, ödeme, bildirimler, raporlama) ayrı bir modül olarak geliştirerek, ileride mikroservislere geçişi kolaylaştırmayı amaçlıyorum.
Asenkron İşlemler: Bildirimler, ödeme webhook’ları ve raporlama gibi zaman alıcı işlemleri, Laravel’in kuyruk sistemiyle (Queue) asenkron hale getirmeyi planlıyorum.

Bu yapı sayesinde projem, başlangıçta hızlıca bir Minimum Viable Product (MVP) olarak hayata geçerken, zamanla ihtiyaç duyulduğunda ölçeklendirilebilecek, bakım ve güncellemeler de zahmetsizce yapılabilecek bir hal alacak.

Proje Kurulumu: Temelleri Sağlam Atmak

Proje başlangıcında ilk işim, Laravel projesini oluşturmak oldu. Modern geliştirme ortamına uygun olarak, Docker kullanarak geliştirme ortamımı oluşturmak, ekip içindeki herkesin aynı koşullarda çalışmasını sağladı. .env dosyasında veritabanı, kuyruk, ödeme servisleri ve diğer API anahtarlarını yapılandırarak projenin temellerini attım.

Ayrıca, modüler yapıyı benimseyebilmek için nwidart/laravel-modules paketini projeme ekledim. Bu sayede, her modülü bağımsız olarak geliştirebiliyor, daha sonra bunları kolaylıkla ayrı mikroservislere dönüştürme şansı elde edebiliyordum.

Güvenli Kimlik Doğrulama ve Yetkilendirme

Güvenlik, API geliştirmede ilk sırada gelmeli. Benim projemde, kullanıcı türleri üç ana kategoriye ayrılıyor: süper admin, admin ve normal kullanıcı (alıcı ve satıcı). Laravel Passport kullanarak OAuth2 tabanlı, token temelli bir kimlik doğrulama sistemi inşa ettim. Böylece her API isteğinde, geçerli bir erişim token’ı kontrol ediliyor ve kullanıcıların rol bazlı yetkilendirmesi, Laravel’in Gate/Policy mekanizması veya spatie/laravel-permission gibi paketlerle sağlanıyor.

Bu yapı, kullanıcı kayıtları, giriş işlemleri ve her türlü güvenlik gereksinimi için esnek ve güçlü bir altyapı sunuyor. Özellikle admin onayı gerektiren işlemlerde (örneğin yeni ilanların veya kullanıcıların aktif hale getirilmesi) sistemin doğru yetkilendirme kontrolünü yapabilmesi, API’nin sağlamlığını garantiliyor.

Ödeme İşlemleri: Iyzico ve Stripe Entegrasyonu

Ödeme süreçlerini iki farklı sistem üzerinden yönetmek benim için önemli bir gereksinimdi.

Stripe: Global pazara hitap eden kullanıcılar için, Laravel Cashier kullanarak Stripe ile abonelik yönetimi ve tek seferlik ödemeler kolaylıkla entegre edildi. Cashier sayesinde, kullanıcı aboneliklerini oluşturmak, yenilemek ve iptal etmek çok daha sorunsuz hale geldi.
Iyzico: Yerel pazara yönelik işlemler için ise Iyzico’nun PHP SDK’sını kullanarak, ödeme form verilerinin toplanması, 3D Secure sürecinin yönetilmesi ve webhook’lar aracılığıyla ödeme sonuçlarının takip edilmesi sağlandı.

Her iki ödeme sisteminde de, ödeme işlemleri güvenli bir şekilde yapılırken, webhooks sayesinde ödeme durumları API üzerinden güncelleniyor. Böylece, hem kullanıcı deneyimi kesintiye uğramıyor hem de sistem, anlık olarak ödeme sonuçlarını işleyebiliyor.

Modüler API Yapısı: Servis ve Repository Katmanları

Projemde, iş mantığını controller’lardan ayırarak servis katmanları oluşturmayı benimsedim. Bu sayede;

Controller’lar yalnızca gelen HTTP isteklerini alıp, servis katmanına yönlendiriyor.
Service Katmanı, tüm iş kurallarını, doğrulamaları ve mantığı içeriyor.
Repository Katmanı, veritabanı erişim işlemlerini merkezi bir noktada topluyor.

Bu katmanlı mimari sayesinde, kod tekrarını en aza indiriyor, gelecekte yapılacak değişiklikleri kolaylaştırıyor ve test edilebilirliği artırıyorum. Her modül, örneğin “İlanlar” veya “Ödemeler” gibi, kendi içinde bu yapıya uygun olarak geliştiriliyor.

Asenkron İşlemler ve Kuyruklama

Kullanıcı deneyimini iyileştirmek için zaman alan işlemleri arkaplana almak şart. Laravel’in kuyruk sistemi ile;

E-posta Bildirimleri: Yeni kullanıcı kaydı, şifre sıfırlama gibi işlemlerde e-postalar asenkron olarak gönderiliyor.
Ödeme Webhook’ları: Hem Stripe hem de Iyzico’dan gelen ödeme bildirimleri kuyruklara alınarak, sistemin yoğunluk anlarında bile sorunsuz işleniyor.
Raporlama İşlemleri: Yoğun veri analizlerini ve rapor oluşturma süreçlerini arkaplanda çalıştırarak, API’nin anında cevap vermesini sağlıyorum.

Redis’i kuyruk bağlantısı olarak kullanıyor, Laravel Horizon ile de kuyruk işlerini ve performansını izliyorum. Bu sayede, kullanıcılar hiçbir zaman yavaşlamış bir API ile karşılaşmıyor.

Bildirim ve Raporlama Modülü: Kullanıcıyla Anında Etkileşim

API’de, kullanıcıları anında bilgilendirmek benim için çok önemliydi. Laravel’in Notification sistemi ile e-posta, SMS (v2’de eklenecek) ve push bildirimlerini entegre ettim. Böylece, kullanıcılarım; kayıt olduklarında, onay bekleyen işlemler olduğunda veya kampanyalardan haberdar edilmek istediklerinde anında bilgilendiriliyor.

Ayrıca, adminler için kapsamlı raporlar sunan bir modül geliştirerek, uygulamanın kullanım istatistiklerini, gelir raporlarını ve kullanıcı aktivitelerini gerçek zamanlı takip edebiliyorum. Bu sayede, stratejik kararlar alırken elimde güncel veriler oluyor.

Dış Servis Entegrasyonları: Google ile Güçlenmek

Güvenlikten performansa, pek çok alanda Google servislerini entegre ettim:

reCAPTCHA: Bot ve spam koruması için, kullanıcı formlarına Google reCAPTCHA ekledim.
Google Maps: İlanların konum bilgilerini göstermek ve adres doğrulama işlemleri için Maps API’den faydalandım.
Google Analytics ve Search Console: API’ye bağlı web uygulamasının performansını ve SEO durumunu izlemek için bu araçları kullanıyorum.

Bu entegrasyonlar, API’nin hem güvenliğini hem de kullanıcı deneyimini büyük ölçüde artırıyor.

Test, Güvenlik ve Performans Optimizasyonu

Geliştirdiğim API’nin güvenilir ve performanslı olmasını sağlamak için;

PHPUnit/Pest ile Birim ve Entegrasyon Testleri: Her modülün ve iş akışının doğru çalıştığından emin olmak için kapsamlı testler yazdım.
API Rate Limiting: Kötü niyetli isteklerin ve aşırı kullanımın önüne geçmek için istek hız sınırlandırması uyguladım.
HTTPS ve Diğer Güvenlik Önlemleri: Tüm trafiği HTTPS üzerinden yürüttüm, CORS ayarlarını ve girdi doğrulamalarını sıkılaştırdım.

Ayrıca, performansı artırmak adına caching, veritabanı optimizasyonları ve sayfalama gibi yöntemleri devreye aldım. Her şeyin sorunsuz çalıştığından emin olmak için sürekli izleme ve profil çıkarma araçlarını kullanıyorum.

API Dökümantasyonu: Scramble & Postman

Projemde, API’nin hem anlaşılır hem de güncel olmasını sağlamak amacıyla iki farklı dokümantasyon aracından yararlandım: Scramble API Dökümantasyonu ve Postman API Koleksiyonu. Aşağıda bu iki aracın sunduğu imkanları ve entegrasyon sürecindeki katkılarını detaylandırıyorum:

Scramble API Dökümantasyonu

Scramble, Swagger benzeri bir yapıya sahip olup, API’nizin görsel ve interaktif olarak sunulmasını sağlıyor. Bu aracı tercih etmemin nedenleri şu şekilde:

Interaktif Arayüz:
Tüm endpoint’ler, HTTP metotları, parametreler ve örnek dönüşler, kullanıcı dostu bir arayüzde detaylandırılıyor. Bu sayede, API’nizi kullanan geliştiriciler isteklerin nasıl yapılandırıldığını ve hangi verilerin beklendiğini anında görebiliyor.
Canlı Test İmkanı:
Dokümantasyon içerisinde yer alan “try-it-out / Send API Request” özelliği ile doğrudan API çağrıları yapabiliyorsunuz. Bu özellik, entegrasyon sürecinde anlık test ve hata ayıklama imkanı sağlayarak, API’nin işleyişine dair pratik bir deneyim sunuyor.
Otomatik Güncelleme:
API’ye eklenen yeni endpoint veya mevcut endpoint’lerde yapılan değişiklikler, dokümantasyona da anında yansıtılıyor. Böylece, her zaman güncel ve doğru bilgi sunarak olası uyumsuzlukların önüne geçiyorum.

Bu yapıyla, API’nin mimari yapısını, veri modellerini ve hata yönetimini net bir şekilde ortaya koyuyor, interaktif örneklerle geliştiricilerin sürece hızla adapte olmasını sağlıyorum. Swagger biraz daha uğraştırıcı olduğu için (bana göre) genelde bunu tercih ediyorum.

Postman API Dokümantasyonu ve Koleksiyonu

Ayrıca, API’nin kullanımını daha da kolaylaştırmak adına Postman üzerinden hazırlanmış kapsamlı bir dokümantasyon ve koleksiyon da sunuyorum. Bu koleksiyonda:

Önceden Tanımlanmış İstekler:
API’deki tüm endpoint’ler için yapılandırılmış örnek istekler mevcut. Bu örnekler, geliştiricilerin hızlıca test yapabilmesini ve entegrasyona başlamasını destekliyor.
Çevresel Yapılandırma:
API anahtarları, tokenlar gibi gizli bilgilerin yönetimi için Postman environment (ortam) değişkenleri kullanılarak, test sürecinin hem güvenli hem de kolaylaştırılmış hale gelmesi sağlanıyor.
Adım Adım Dokümantasyon:
Her API endpoint’i için detaylı açıklamalar, istek ve cevap örnekleri ile kullanım senaryoları dokümantasyona eklenmiş durumda. Bu sayede, API’nin nasıl çalıştığı ve hangi durumlarda nasıl davranacağı, geliştiricilere net olarak aktarılıyor.

Postman koleksiyonu, API entegrasyon sürecinde karşılaşılabilecek sorunları minimuma indirerek, hata ayıklama ve test aşamalarını oldukça kolaylaştırıyor.

Neden Bu Dokümantasyon Yöntemleri?

API dokümantasyonu, projenizin sürdürülebilirliği ve geliştirici deneyimi açısından kritik bir öneme sahip. Scramble ile sağlanan interaktif ve otomatik güncellenen belge yapısı, API’nizin tüm gelişmelerini anında yansıtırken; Postman koleksiyonu, canlı test imkanları ve önceden tanımlanmış istek örnekleriyle entegrasyon sürecinde zaman kazandırıyor. Bu iki yöntem, API’nin kullanımının kolay, anlaşılır ve güncel kalmasını sağlarken, aynı zamanda geliştiricilerin hata ayıklama ve entegrasyon süreçlerini de hızlandırıyor.

CI/CD ve Dağıtım: Koddan Canlıya Sorunsuz Geçiş

Projemin geliştirme sürecinde, GitHub Actions ile CI/CD boru hattı oluşturmayı ihmal etmedim. Her push’ta otomatik testler çalışıyor, başarılı sonuçlar alınca Docker tabanlı bir ortamda derlenip, staging ve ardından prod ortamına dağıtım gerçekleştiriliyor. Böylece kodun her an güncel, test edilmiş ve canlıya geçmeye hazır olduğundan emin oluyorum.

Özetlemem Gerekirse

Bu projede, Laravel’in gücünü ve esnekliğini kullanarak, modüler, ölçeklenebilir ve profesyonelce inşa edilmiş bir RESTful API ortaya çıkardım. Hem yerel hem de global ödeme sistemlerini entegre ederek, güvenli kimlik doğrulama, asenkron işlemler ve kapsamlı raporlama gibi kritik özellikleri aynı çatı altında topladım. Tüm bu adımlar, benim için bir API geliştirme sürecinde nasıl sistematik, profesyonel ve yenilikçi bir yaklaşım benimsediğimi gösteriyor.

Eğer siz de benzer bir projeye girişmeyi planlıyorsanız, bu yol haritası size ilham verebilir ve pratikte nelere dikkat etmeniz gerektiği konusunda yol gösterebilir. Geliştirme sürecinde öğrendiğim en önemli şey; her aşamada temiz kod, modülerlik ve esnekliği ön planda tutmak, gelecekte karşınıza çıkabilecek değişikliklere kolayca adapte olmanızı sağlıyor.

DİPNOT: Bu yazı daha sonra görsellerle pekiştirilebilir veya yazılanlar zamanla değişebilir. Değişiklikler kaçırmamak için ilgili bağlantılardan takipte kalabilirsiniz…

Yazımı beğendiyseniz paylaşmayı ve düşüncelerinizi yorumlarda belirtmeyi unutmayın! Ayrıca; eksik, hatalı veya yanlış bir bilgi olması halinde yorumlarda (mümkünse bilginin kaynağıyla beraber) belirttiğiniz takdirde ilgili düzenlemeyi yaparım...

Bunun gibi daha fazla paylaşım için takipte kalın:

Laravel ile Modüler ve Ölçeklenebilir RESTful API Geliştirme Yolculuğum

Table of contents