API Kaynakları Nedir?

Question

Accepted Answer

**API Kaynakları** (API Resources), Eloquent modellerinin (ve koleksiyonlarının) API yanıtları için **JSON'a serileştirilmesini** kontrol eden dönüştürme sınıflarıdır. API çıktısını tam olarak şekillendirebilirsiniz — hangi alanları açığa çıkaracağınızı seçer, bunları yeniden adlandırır, değerleri biçimlendirir ve ilgili verileri ekleyebilirsiniz — API temsilini veritabanı yapısından ayırırsınız.

## Sorun: ham modelleri açığa çıkarmak

```php
// ❌ returning a model directly exposes ALL columns (maybe including sensitive ones)
return User::find($id);   // { id, name, email, password_hash, internal_notes, ... } 😱
```

## Çözüm: bir API Kaynağı

```php
<?php
// php artisan make:resource UserResource
class UserResource extends JsonResource {
    public function toArray($request): array {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            // password and internal fields deliberately OMITTED
            'joined' => $this->created_at->toDateString(),   // format a value
            'is_admin' => (bool) $this->is_admin,
            // include related data (conditionally loaded)
            'posts' => PostResource::collection($this->whenLoaded('posts')),
        ];
    }
}
```

```php
// use it in a controller
return new UserResource($user);                  // a single model
return UserResource::collection(User::all());     // a collection
```

Kaynağın `toArray()` metodu tam olarak JSON şeklini tanımlar — hangi alanların görüneceğini kontrol edersiniz, bunları yeniden adlandırabilir ve biçimlendirebilir, ilgili kaynakları ekleyebilirsiniz. Duyarlı alanlar basitçe dahil edilmez.

## Koşullu ve iç içe veriler

```php
return [
    'id' => $this->id,
    'secret' => $this->when($request->user()->isAdmin(), $this->secret),  // conditional field
    'posts' => PostResource::collection($this->whenLoaded('posts')),       // only if eager-loaded
];
```

## Neden önemli

API Kaynakları, Laravel'de iyi tasarlanmış, güvenli API'ler oluşturmak için önemlidir — JSON çıktısı üzerinde hassas kontrol sağlarlar, bu da hem **güvenlik** hem de API tasarımı açısından önemlidir.

En kritik fayda **veri sızıntılarını önlemektir**: Eloquent modellerini doğrudan döndürmek tüm sütunlarını açığa çıkarır (potansiyel olarak parola hash'leri, dahili işaretçiler veya diğer duyarlı verileri içerebilir — ciddi bir güvenlik açığı), oysa API Kaynakları hangi alanları açığa çıkaracağınızı açıkça seçmenize izin verir ve duyarlı verilerin istemcilere asla ulaşmamasını sağlar.

Güvenliğin ötesinde, **API temsilini veritabanı şemasından ayırarak** temiz API tasarımı sağlarlar — alanları yeniden adlandırabilir, değerleri biçimlendirebilir (tarihler, mantıksal değerler), iç içe/ilgili verileri yapılandırabilir ve izinlere dayalı olarak koşullu olarak alanlar ekleyebilirsiniz; bütün bunlar adanmış bir dönüştürme sınıfında yapılır.

Bu, API sözleşmesini veritabanı yapısına bağlı olmak yerine istikrarlı ve kasıtlı tutar.

API Kaynakları anlamak — JSON çıktısını nasıl şekillendirir, açık alan kontrolünün güvenlik yararı ve koşullu alanlar ve iç içe kaynaklar gibi özellikler — profesyonel Laravel API'leri oluşturmak için önemli bilgidir, çünkü ham modelleri açığa çıkarmak hem güvensizdir hem de zayıf tasarımdır.

REST/JSON API'leri günümüzde Laravel'in birincil kullanımı olarak ve yanıt şeklini kontrol etmek (güvenli ve temiz bir şekilde) yaygın ve önemli bir ihtiyaç olduğundan, API Kaynakları sık kullanılan, değerli bir araçtır ve iyi inşa edilmiş, güvenli API'leri veri sızan veya çıktısını veritabanına sıkı bir şekilde bağlayan API'lerden ayırır.