Laravel API Oluşturma Rehberi: Temelden İleri Seviyeye

Laravel API Oluşturma Rehberi: Temelden İleri Seviyeye

Laravel, modern web uygulamaları ve API’ler geliştirmek için güçlü ve zarif bir PHP framework’üdür. RESTful API’ler oluşturmak için sunduğu araçlar ve kolaylıklar sayesinde geliştiriciler arasında popüler bir seçimdir. Bu rehberde, Laravel kullanarak sıfırdan bir API oluşturma sürecini adım adım ele alacak, pratik bilgiler ve kod örnekleri sunacağız.

API Nedir ve Neden Laravel?

API (Application Programming Interface), farklı yazılım sistemlerinin birbiriyle iletişim kurmasını sağlayan bir dizi kural ve protokoldür. Bir API, bir uygulamanın diğerine belirli bir işlevi gerçekleştirmesi veya veri sağlaması için istek göndermesine olanak tanır. Örneğin, bir mobil uygulama, arka uç sunucusundaki bir API aracılığıyla ürün bilgilerini alabilir veya sipariş oluşturabilir.

Laravel’in API geliştirmede öne çıkmasının başlıca nedenleri şunlardır:

• Kolay Kurulum ve Yapılandırma: Hızlı proje oluşturma ve .env dosyası ile kolay yapılandırma.
• RESTful Mimari Desteği: Kaynak tabanlı (resource-based) API’ler için güçlü yönlendirme ve denetleyici (controller) yapıları.
• ORM (Eloquent): Veritabanı etkileşimini basitleştiren güçlü ve sezgisel bir Object-Relational Mapper.
• Kimlik Doğrulama ve Yetkilendirme: Laravel Sanctum gibi entegre çözümlerle API güvenliğini kolayca sağlama.
• Validasyon: Gelen istek verilerini kolayca doğrulama mekanizmaları.
• API Kaynakları (Resources): API yanıtlarını formatlamak ve dönüştürmek için esnek bir yapı.
• Geniş Topluluk ve Dokümantasyon: Karşılaşılan sorunlara hızlı çözümler bulma imkanı.

Laravel Projesi Kurulumu ve Temel Yapılandırma

Yeni bir Laravel projesi oluşturmak oldukça basittir. Terminalinizi açın ve aşağıdaki komutu çalıştırın:

composer create-project laravel/laravel my-api-project
cd my-api-project

Proje dizinine girdikten sonra, .env dosyasını yapılandırmanız gerekecektir. Bu dosya, veritabanı bağlantı bilgileri, uygulama anahtarı ve diğer çevresel değişkenleri içerir.

APP_NAME="My Laravel API"
APP_ENV=local
APP_KEY=base64:YOUR_APP_KEY_HERE (Bu otomatik oluşturulur)
APP_DEBUG=true
APP_URL=http://localhost:8000

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=my_api_database
DB_USERNAME=root
DB_PASSWORD=

Veritabanınızı (örneğin my_api_database) oluşturduktan sonra, Laravel’in migration’larını çalıştırmak için aşağıdaki komutu kullanın:

php artisan migrate

Bu komut, Laravel’in varsayılan users ve password_reset_tokens tablolarını veritabanınıza ekleyecektir.

API Uç Noktaları ve Veritabanı Etkileşimi

Bir API’nin temelini, veritabanındaki kaynakları (resource) yöneten uç noktalar (endpoints) oluşturur. Bir “Ürünler” (Products) API’si oluşturarak bu süreci inceleyelim.

Model ve Migration Oluşturma

İlk olarak, Product modelimizi ve bu modele karşılık gelen veritabanı tablosunu oluşturmak için bir migration dosyası hazırlayalım:

php artisan make:model Product -m

Bu komut, app/Models/Product.php dosyasını ve database/migrations klasöründe yeni bir migration dosyasını oluşturacaktır. Migration dosyasını açın ve up metodunu aşağıdaki gibi düzenleyin:

// database/migrations/XXXX_XX_XX_XXXXXX_create_products_table.php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('products', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->text('description')->nullable();
            $table->decimal('price', 8, 2);
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('products');
    }
};

Ardından, migration’ı çalıştırmak için php artisan migrate komutunu tekrar kullanın.

Şimdi Product modelini düzenleyerek fillable özelliklerini tanımlayalım. Bu, hangi alanların toplu atama (mass assignment) yoluyla doldurulabileceğini belirtir:

// app/Models/Product.php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    use HasFactory;

    protected $fillable = [
        'name',
        'description',
        'price',
    ];
}

API Controller Oluşturma

API isteklerini işleyecek bir controller oluşturalım. --api bayrağını kullanarak RESTful API metodlarını içeren bir controller iskeleti oluşturabiliriz:

php artisan make:controller Api/ProductController --api

Bu komut, app/Http/Controllers/Api/ProductController.php dosyasını oluşturacaktır. İçeriğini aşağıdaki gibi düzenleyelim:

// app/Http/Controllers/Api/ProductController.php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\Product;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class ProductController extends Controller
{
    /
     * Display a listing of the resource.
     */
    public function index()
    {
        return response()->json(Product::all());
    }

    /
     * Store a newly created resource in storage.
     */
    public function store(Request $request)
    {
        $request->validate([
            'name' => 'required|string|max:255',
            'description' => 'nullable|string',
            'price' => 'required|numeric|min:0',
        ]);

        $product = Product::create($request->all());
        return response()->json($product, Response::HTTP_CREATED); // 201 Created
    }

    /
     * Display the specified resource.
     */
    public function show(Product $product)
    {
        return response()->json($product);
    }

    /
     * Update the specified resource in storage.
     */
    public function update(Request $request, Product $product)
    {
        $request->validate([
            'name' => 'sometimes|string|max:255',
            'description' => 'nullable|string',
            'price' => 'sometimes|numeric|min:0',
        ]);

        $product->update($request->all());
        return response()->json($product);
    }

    /
     * Remove the specified resource from storage.
     */
    public function destroy(Product $product)
    {
        $product->delete();
        return response()->json(null, Response::HTTP_NO_CONTENT); // 204 No Content
    }
}

API Rotalarını Tanımlama

API rotaları routes/api.php dosyasında tanımlanır. Laravel’in apiResource metodu, CRUD (Create, Read, Update, Delete) operasyonları için tek bir satırda tüm rotaları oluşturmamızı sağlar:

// routes/api.php

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Api\ProductController;

Route::get('/user', function (Request $request) {
    return $request->user();
})->middleware('auth:sanctum');

Route::apiResource('products', ProductController::class);

Bu tek satır, aşağıdaki rotaları otomatik olarak oluşturur:

• GET /api/products -> ProductController@index
• POST /api/products -> ProductController@store
• GET /api/products/{product} -> ProductController@show
• PUT/PATCH /api/products/{product} -> ProductController@update
• DELETE /api/products/{product} -> ProductController@destroy

Artık php artisan serve komutu ile sunucuyu başlatıp Postman veya Insomnia gibi bir araçla API’nizi test edebilirsiniz.

API Kimlik Doğrulama (Laravel Sanctum ile)

Çoğu API, kullanıcıların kimliğini doğrulamayı ve yetkilendirmeyi gerektirir. Laravel Sanctum, SPA (Single Page Application), mobil uygulamalar ve basit token tabanlı API’ler için hafif bir kimlik doğrulama sistemidir.

Sanctum Kurulumu

Sanctum’u projenize eklemek için:

composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate

Bu komutlar, Sanctum’un gerekli dosyalarını ve personal_access_tokens tablosunu oluşturacaktır.

Kullanıcı Girişi ve Token Oluşturma

API’nize giriş yapmak ve bir kimlik doğrulama token’ı almak için bir endpoint oluşturalım.

Yeni bir controller oluşturun:

php artisan make:controller Api/AuthController

AuthController içeriğini aşağıdaki gibi düzenleyin:

// app/Http/Controllers/Api/AuthController.php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Http\Response;

class AuthController extends Controller
{
    public function login(Request $request)
    {
        $credentials = $request->validate([
            'email' => 'required|email',
            'password' => 'required',
        ]);

        if (!Auth::attempt($credentials)) {
            return response()->json(['message' => 'Geçersiz kimlik bilgileri.'], Response::HTTP_UNAUTHORIZED); // 401 Unauthorized
        }

        $user = Auth::user();
        $token = $user->createToken('auth_token')->plainTextToken;

        return response()->json([
            'message' => 'Giriş başarılı.',
            'access_token' => $token,
            'token_type' => 'Bearer',
        ]);
    }

    public function logout(Request $request)
    {
        $request->user()->currentAccessToken()->delete();

        return response()->json(['message' => 'Çıkış başarılı.']);
    }

    public function user(Request $request)
    {
        return response()->json($request->user());
    }
}

routes/api.php dosyanıza bu endpoint’leri ekleyin:

// routes/api.php

use App\Http\Controllers\Api\AuthController;

// ... diğer rotalar

Route::post('/login', [AuthController::class, 'login']);

Route::middleware('auth:sanctum')->group(function () {
    Route::post('/logout', [AuthController::class, 'logout']);
    Route::get('/user', [AuthController::class, 'user']); // Kimliği doğrulanmış kullanıcıyı döndürür
    Route::apiResource('products', ProductController::class); // Ürün rotalarını koruma altına alıyoruz
});

Artık products rotalarına erişmek için HTTP başlığında (Header) Authorization: Bearer YOUR_ACCESS_TOKEN şeklinde bir token göndermeniz gerekecektir.

Pratik İpuçları ve Sonuç

Validasyon (Validation)

Controller’ınızda Request nesnesi üzerinde validate() metodunu kullanmak yerine, daha temiz ve yeniden kullanılabilir kod için Form Request sınıflarını tercih edebilirsiniz:

php artisan make:request StoreProductRequest

app/Http/Requests/StoreProductRequest.php dosyasını düzenleyin:

// app/Http/Requests/StoreProductRequest.php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreProductRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true; // İstek yetkilendirme mantığını buraya ekleyebilirsiniz
    }

    public function rules(): array
    {
        return [
            'name' => 'required|string|max:255',
            'description' => 'nullable|string',
            'price' => 'required|numeric|min:0',
        ];
    }
}

Ve controller’ınızda Request yerine StoreProductRequest‘i kullanın:

// app/Http/Controllers/Api/ProductController.php (store metodu)

use App\Http\Requests\StoreProductRequest;

public function store(StoreProductRequest $request)
{
    $product = Product::create($request->validated()); // validated() sadece geçerli verileri döndürür
    return response()->json($product, Response::HTTP_CREATED);
}

API Kaynakları (API Resources)

API yanıtlarınızı standartlaştırmak ve model verilerini dönüştürmek için API Resources kullanın. Bu, özellikle ilişkisel verileri yüklerken veya belirli alanları gizlerken çok faydalıdır.

php artisan make:resource ProductResource

app/Http/Resources/ProductResource.php dosyasını düzenleyin:

// app/Http/Resources/ProductResource.php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class ProductResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'product_name' => $this->name, // Alan adını değiştirdik
            'details' => $this->description,
            'price_usd' => number_format($this->price, 2), // Fiyatı formatladık
            'created_at' => $this->created_at->format('Y-m-d H:i:s'),
            'updated_at' => $this->updated_at->format('Y-m-d H:i:s'),
        ];
    }
}

Controller’ınızda kullanımı:

// app/Http/Controllers/Api/ProductController.php

use App\Http\Resources\ProductResource;

// index metodu
public function index()
{
    return ProductResource::collection(Product::all()); // Koleksiyon için
}

// show metodu
public function show(Product $product)
{
    return new ProductResource($product); // Tek bir öğe için
}

Hata Yönetimi (Error Handling)

Laravel, güçlü bir hata yönetimi sunar. Özel durumları (exceptions) yakalamak ve uygun HTTP durum kodlarıyla JSON yanıtları döndürmek önemlidir. Örneğin, bir kaynak bulunamadığında 404 Not Found yanıtı vermek için Laravel’in varsayılan model binding özelliği yeterlidir.

Test Etme

API’nizi geliştirirken Postman, Insomnia veya cURL gibi araçlarla endpoint’lerinizi düzenli olarak test edin. Laravel ayrıca kapsamlı PHPUnit testleri yazma yeteneği de sunar, bu da API’nizin güvenilirliğini artırır.

Sonuç

Bu rehberde, Laravel kullanarak bir RESTful API’nin temel bileşenlerini nasıl oluşturacağınızı öğrendiniz. Model, migration, controller, rota tanımlama, Laravel Sanctum ile kimlik doğrulama ve pratik ipuçları gibi konuları ele aldık. Laravel’in sağladığı araçlar sayesinde, güçlü, ölçeklenebilir ve bakımı kolay API’ler geliştirmek oldukça basittir. Daha karmaşık senaryolar için, API kaynakları, middleware’ler, rate limiting ve caching gibi Laravel’in diğer özelliklerini keşfetmeye devam edebilirsiniz.

Sıkça Sorulan Sorular (SSS)

S: RESTful API nedir?

C: RESTful API, web servisleri için bir mimari stildir. Temel prensipleri arasında kaynak tabanlı olması (URI’ler kaynakları temsil eder), durum bilgisiz (stateless) olması (her istek sunucuya gerekli tüm bilgiyi taşır), istemci-sunucu ayrımı ve standart HTTP metodlarının (GET, POST, PUT, DELETE) kullanılması bulunur.

S: Laravel’de middleware ne işe yarar?

C: Middleware’ler, HTTP istekleri uygulamaya ulaşmadan önce veya yanıtlar istemciye gönderilmeden önce çalıştırılan kod katmanlarıdır. Örneğin, auth:sanctum middleware’i, bir isteğin kimliği doğrulanmış bir kullanıcıdan gelip gelmediğini kontrol eder.

S: API Resources neden kullanılır?

C: API Resources, model verilerini API yanıtına dönüştürmek için bir katman sağlar. Bu sayede, veritabanı yapınızdan bağımsız olarak API yanıtınızın yapısını kontrol edebilir, belirli alanları gizleyebilir, formatlayabilir veya ilişkili verileri kolayca dahil edebilirsiniz. Bu, API’nizin dış dünyaya sunduğu veriyi standartlaştırmanıza yardımcı olur.

S: CORS nedir ve Laravel’de nasıl çözülür?

C: CORS (Cross-Origin Resource Sharing), bir web sayfasındaki JavaScript’in, farklı bir kaynaktan (domain, protokol veya port) gelen kaynaklara istek göndermesini sağlayan bir güvenlik mekanizmasıdır. Tarayıcılar, güvenlik nedeniyle genellikle aynı kaynak politikasını uygular. Laravel, fruitcake/laravel-cors paketi ile CORS’u kolayca yönetmenizi sağlar. Bu paket, gelen isteklere uygun CORS başlıklarını ekleyerek tarayıcıların farklı kaynaklardan API’nize erişmesine izin verir.

S: Laravel’de Rate Limiting (İstek Sınırlandırma) nasıl yapılır?

C: Laravel, API’nizin belirli bir zaman diliminde alabileceği istek sayısını sınırlamak için yerleşik Rate Limiting özelliğine sahiptir. routes/api.php dosyanızda throttle:api middleware’ini kullanarak veya kendi özel rate limiter’larınızı tanımlayarak bunu yapabilirsiniz. Örneğin, Route::middleware('throttle:60,1')->group(...) ile dakikada 60 istekle sınırlayabilirsiniz.