Günümüzde RESTful API'ler, farklı platformların birbiriyle veri alışverişinde bulunmasını sağlayan en yaygın yöntemlerden biridir. Laravel, gelişmiş özellikleriyle RESTful API geliştirmek için en popüler PHP framework’lerinden biridir. Ancak, doğru API tasarımı yapmak, yalnızca bir rota ve kontrolcü oluşturmakla bitmez.

Bu yazıda, RESTful API standartlarına uygun bir API geliştirmek için HTTP metodları, durum kodları, hata yönetimi, veri formatları ve HATEOAS prensibi gibi önemli konuları ele alacağız.

1. RESTful API Nedir?

REST (Representational State Transfer), HTTP protokolünü kullanarak istemci ile sunucu arasında veri alışverişini sağlayan bir mimaridir. RESTful API, bu prensiplere uygun olarak geliştirilen API’dir.

REST Prensipleri

1. Kaynak Odaklı: API, belirli kaynaklara (resources) yönelik işlemleri gerçekleştirmelidir.
2. HTTP Metodları Kullanımı: GET, POST, PUT, DELETE gibi standart HTTP metodları kullanılmalıdır.
3. Doğru HTTP Durum Kodları: API yanıtları, 200, 201, 400, 404, 500 gibi uygun HTTP durum kodları içermelidir.
4. JSON Formatı: API'lerin veri alışverişi için genellikle JSON formatı kullanılır.
5. Stateless (Durumsuz) Olma: Her API çağrısı bağımsız olmalı ve önceki çağrıların durumuna bağlı olmamalıdır.
6. HATEOAS Desteği: (Hypermedia as the Engine of Application State) API, istemcinin diğer işlemleri keşfetmesine yardımcı olacak linkleri içermelidir.

2. Laravel ile RESTful API Geliştirme

Laravel, API Resource Controller, Middleware, Sanctum (Token Authentication) ve API Resources gibi özelliklerle RESTful API geliştirme sürecini oldukça kolaylaştırır. Şimdi adım adım RESTful API oluşturacağız.

Adım 1: Laravel Projesi Kurulumu

composer create-project laravel/laravel restful-api
cd restful-api
php artisan serve

Adım 2: Model ve Migration Oluşturma

Bir Post modeli oluşturarak API’nin temel veri kaynağını oluşturacağız.

php artisan make:model Post -m

Migration dosyasını açarak aşağıdaki gibi düzenleyelim:

// database/migrations/xxxx_xx_xx_create_posts_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()
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->string('title');
            $table->text('content');
            $table->timestamps();
        });
    }

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

Veritabanını migrate edelim:

php artisan migrate

3. API Controller Oluşturma

RESTful standartlarına uygun bir PostController oluşturacağız:

php artisan make:controller API/PostController --api

// app/Http/Controllers/API/PostController.php
namespace App\Http\Controllers\API;

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

class PostController extends Controller
{
    // Tüm postları getir
    public function index()
    {
        return response()->json(Post::all(), Response::HTTP_OK);
    }

    // Yeni post oluştur
    public function store(Request $request)
    {
        $request->validate([
            'title' => 'required|string|max:255',
            'content' => 'required|string',
        ]);

        $post = Post::create($request->all());

        return response()->json($post, Response::HTTP_CREATED);
    }

    // Belirli bir postu getir
    public function show(Post $post)
    {
        return response()->json($post, Response::HTTP_OK);
    }

    // Post güncelle
    public function update(Request $request, Post $post)
    {
        $request->validate([
            'title' => 'sometimes|required|string|max:255',
            'content' => 'sometimes|required|string',
        ]);

        $post->update($request->all());

        return response()->json($post, Response::HTTP_OK);
    }

    // Postu sil
    public function destroy(Post $post)
    {
        $post->delete();

        return response()->json(null, Response::HTTP_NO_CONTENT);
    }
}

4. API Rotaları Tanımlama

// routes/api.php
use App\Http\Controllers\API\PostController;

Route::apiResource('posts', PostController::class);

5. HTTP Durum Kodları ve Hata Yönetimi

Laravel’de API hata yönetimi için Exception Handling kullanabiliriz.

Özel bir Exception Handler yazalım:

// app/Exceptions/Handler.php
use Illuminate\Database\Eloquent\ModelNotFoundException;
use Illuminate\Http\Response;
use Illuminate\Validation\ValidationException;

public function render($request, Throwable $exception)
{
    if ($exception instanceof ModelNotFoundException) {
        return response()->json([
            'error' => 'Kayıt bulunamadı'
        ], Response::HTTP_NOT_FOUND);
    }

    if ($exception instanceof ValidationException) {
        return response()->json([
            'error' => $exception->errors()
        ], Response::HTTP_UNPROCESSABLE_ENTITY);
    }

    return parent::render($request, $exception);
}

HTTP Durum Kodları

• 200 OK: İstek başarılı.

• 201 Created: Yeni bir kaynak oluşturuldu.

• 204 No Content: İstek başarılı, ancak yanıt gövdesi yok.

• 400 Bad Request: İstek geçersiz.

• 401 Unauthorized: Kimlik doğrulama gerekiyor.

• 404 Not Found: Kaynak bulunamadı.

• 500 Internal Server Error: Sunucu hatası.

6. API Resource Kullanımı

Laravel’de API Resource kullanarak API yanıtlarını düzenleyebiliriz.

php artisan make:resource PostResource

// app/Http/Resources/PostResource.php
namespace App\Http\Resources;

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

class PostResource extends JsonResource
{
    public function toArray(Request $request)
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'content' => $this->content,
            'created_at' => $this->created_at->toDateTimeString(),
            'updated_at' => $this->updated_at->toDateTimeString(),
            '_links' => [
                'self' => route('posts.show', $this->id),
                'update' => route('posts.update', $this->id),
                'delete' => route('posts.destroy', $this->id),
            ]
        ];
    }
}

PostController’da PostResource kullanımı:

use App\Http\Resources\PostResource;

public function index()
{
    return PostResource::collection(Post::all());
}

public function show(Post $post)
{
    return new PostResource($post);
}

7. HATEOAS Desteği

HATEOAS (Hypermedia as the Engine of Application State), API’nin istemcinin ilerleyebileceği yolları göstermesini sağlar. API Resource kullanarak bağlantılar ekledik. Bu sayede istemci, API'nin sunduğu diğer işlemleri kolayca keşfedebilir.

HATEOAS Örneği

Bir Post kaynağı için HATEOAS uygulaması yapalım. Her Post kaynağına, ilgili kaynaklara erişim sağlayan linkler ekleyelim.

public function show(Post $post)
{
    $post->links = [
        'self' => url("/api/posts/{$post->id}"),
        'comments' => url("/api/posts/{$post->id}/comments"),
        'author' => url("/api/users/{$post->user_id}"),
    ];

    return response()->json($post, 200);
}

Bu örnekte, Post kaynağına self, comments ve author linkleri eklenmiştir. Bu sayede, API kullanıcıları, ilgili kaynaklara kolayca erişebilir.

Sonuç

Bu yazıda Laravel ile RESTful API geliştirmenin en iyi uygulamalarını ele aldık:

✔ Doğru HTTP metodları ve durum kodları
✔ API Resource ile özelleştirilmiş JSON formatı
✔ HATA yönetimi için özel Exception Handling
✔ HATEOAS prensibine uygun API tasarımı

Bu yapıyı kullanarak standartlara uygun ve ölçeklenebilir API’ler geliştirebilirsiniz. 🚀