Hva er API-ressurser?

Question

Accepted Answer

**API-ressurser** er transformasjonsklasser som kontrollerer hvordan Eloquent-modeller (og samlinger) blir **serialisert til JSON** for API-responser. De lar deg forme API-utdataene presist — velge hvilke felt som skal eksponeres, gi dem nytt navn, formatere verdier og inkludere relaterte data — og kobler dermed API-representasjonen fra databasestrukturen.

## Problemet: å eksponere råmodeller

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

## Løsningen: en API-ressurs

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

Ressursens `toArray()` definerer nøyaktig JSON-formen — du kontrollerer hvilke felt som vises, gir dem nytt navn og formaterer dem, og inkluderer relaterte ressurser. Sensitive felt er rett og slett ikke inkludert.

## Betinget og nestet 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
];
```

## Hvorfor det er viktig

API-ressurser er viktige for å bygge veldesignede, sikre API-er i Laravel — de gir deg presist kontroll over JSON-utdataene, noe som betyr mye for både **sikkerhet** og API-design.

Den viktigste fordelen er **å forhindre datalekkasje**: å returnere Eloquent-modeller direkte eksponerer alle kolonnene deres (potensielt inkludert passordhasher, interne flagg eller andre sensitive data — en alvorlig sårbarhet), mens API-ressurser lar deg eksplisitt velge hvilke felt som skal eksponeres, og sikrer at sensitive data aldri når klientene.

Utenfor sikkerhet muliggjør de rent API-design ved å **koble API-representasjonen fra databaseskjemaet** — du kan gi felt nytt navn, formatere verdier (datoer, boolske verdier), strukturere nestet/relaterte data og betinget inkludere felt basert på tillatelser, alt i en dedikert transformasjonsklasse.

Dette holder API-kontrakten stabil og bevisst i stedet for koblet til intern tabelstruktur.

Å forstå API-ressurser — hvordan de former JSON-utdataene, sikkerhetsforden av eksplisitt feltkontroll, og funksjoner som betingede felt og nestede ressurser — er viktig kunnskap for å bygge profesjonelle Laravel-API-er, siden eksponering av råmodeller både er usikker og dårlig design.

Ettersom REST/JSON-API-er er en primær bruk av Laravel i dag, og kontroll over responsform (trygt og rent) er et vanlig, viktig behov, er API-ressurser et hyppig brukt, verdifullt verktøy som skiller velbyggede, sikre API-er fra de som lekker data eller sterkt kobler sitt utdata til databasen.