Mitä ovat API-resurssit?

Question

Accepted Answer

**API-resurssit** ovat transformaatioklasseja, jotka hallitsevat sitä, miten Eloquent-mallit (ja kokoelmat) **serialisoidaan JSON-muotoon** API-vastausten yhteydessä. Ne antavat sinulle tarkat mahdollisuudet muokata API-tulosta — voit valita, mitkä kentät näytetään, nimetä ne uudelleen, muotoilla arvot ja sisällyttää liittyviä tietoja — irrottaen API-esityksen tietokannan rakenteesta.

## Ongelma: raakojen mallien paljastaminen

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

## Ratkaisu: API-resurssi

```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
```

Resurssien `toArray()`-metodi määrittelee täsmälleen JSON-rakenteen — sinä hallitset, mitkä kentät näkyvät, nimeät ne uudelleen ja muotoilet niitä sekä sisällytät liittyvät resurssit. Arkaluonteiset kentät yksinkertaisesti jätetään pois.

## Ehdollinen ja sisäkkäinen data

```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
];
```

## Miksi tämä on tärkeää

API-resurssit ovat tärkeitä hyvin suunniteltujen ja turvallisten API-rajapintojen rakentamiseen Laravelissa — ne antavat sinulle tarkat mahdollisuudet hallita JSON-tulosta, mikä on tärkeää sekä **turvallisuuden** että API-suunnittelun kannalta.

Kriittisin hyöty on **tietovuotojen estäminen**: Eloquent-mallien palauttaminen suoraan paljastaa kaikki niiden sarakkeet (mahdollisesti salasanahajautuksia, sisäisiä lippuja tai muita arkaluonteisia tietoja — vakava haavoittuvuus), kun taas API-resurssit antavat sinulle mahdollisuuden valita eksplisiittisesti, mitkä kentät näytetään, varmistaen ettei arkaluonteinen tieto koskaan päädy asiakkaille.

Turvallisuuden lisäksi ne mahdollistavat siistin API-suunnittelun **irrottamalla API-esityksen tietokannan skeemasta** — voit nimetä kentät uudelleen, muotoilla arvot (päivämäärät, loogiset arvot), strukturoida sisäkkäisen/liittyvän datan ja ehdollisesti sisällyttää kenttiä käyttöoikeuksien perusteella, kaikki omassa transformaatioluokassa.

Tämä pitää API-sopimuksen vakaana ja tarkoituksellisena sen sijaan, että se olisi sidottu sisäiseen taulukon rakenteeseen.

API-resurssien ymmärtäminen — miten ne muovaavat JSON-tulosta, eksplisiittisen kenttähallinnan turvallisuushyödyt ja ehdollisten kenttien ja sisäkkäisten resurssien kaltaiset ominaisuudet — on tärkeä tieto ammattimaisten Laravel-API-rajapintojen rakentamiselle, sillä raakojen mallien paljastaminen on sekä turvaton että huonoa suunnittelua. Koska REST/JSON-API-rajapinnat ovat ensisijainen Laravelin käyttötapa nykyään ja koska vastausmuodon hallinta (turvallisesti ja siististi) on yleinen, tärkeä tarve, API-resurssit ovat usein käytettävä, arvokas työkalu, joka erottaa hyvin rakennetut, turvalliset API-rajapinnat niistä, jotka vuotavat tietoja tai kytkeytyvät tiukasti tietokantaan.