Cad iad API Resources?

Question

Accepted Answer

**API Resources** ná ranganna claochlaithe a rialaíonn conas a dhéantar samhlacha Eloquent (agus bailiúcháin) a **sheirialú go JSON** do fhreagairtí API. Tugann siad deis duit an t-aschur API a dhéanamh go beacht — ag roghnú cé na réimsí a nochtadh, ag athainmniú orthu, ag formáidiú luachanna, agus ar an sóid ag gabhháil le sonraí gaolmhara — ag dícheangal an ionadaithí API ó struchtúr an bhunachair sonraí.

## An fhadhb: miodlanna amh a nochtadh

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

## An réiteach: API Resource

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

Sainmhíníonn `toArray()` an acmhainne go beacht cruth an JSON — tú a rialaíonn cé na réimsí a bhíonn ann, athainmniú agus formáidiú orthu, agus acmhainní gaolmhara a ghabháil. Ní bhíonn réimsí íogair san áireamh.

## Sonraí coinníollach agus neadaithe

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

## Cén fáth a bhfuil sé tábhachtach

Tá API Resources tábhachtach do APIs dea-dheartha, slán a thógáil i Laravel — tugann siad rialú beacht duit ar aschur JSON, rud a bhíonn ábhachtach i gcomhair beirt **slándála** agus dearadh API.

Is é an buntáiste is criticiúil ná **sceimh sonraí a chosc**: má fhilleann tú samhlacha Eloquent go díreach, nochtann siad na colúin ar fad (b'fhéidir go n-áirítear hais fhocal fhaire, bratacha inmheánacha, nó sonraí íogair eile — gné bhocht — gur ionann agus API Resources ó thaobh gur ligeann siad duit a dhíriú a roghnú cé na réimsí a nochtadh, ag cinntiú nach gcuirtear sonraí íogair riamh ar aghaidh chuig cliaint.

Thar an chosaint, tugann siad ar an spréacharnach API amhlaidh a dhéanamh trí **ionadaithí API a dhícheangal ó scéim an bhunachair sonraí** — is féidir leat réimsí a athainmniú, luachanna a fhormáidiú (dátaí, booleana), sonraí neadaithe/gaolmhara a struchtúrú, agus réimsí go coinníollach a ghabháil bunaithe ar ceadanna, go léir i rang claochlaithe dírithe.

Coimeádann sé an conradh API seasmhach agus i bhfeidhm seachas greamaithe do struchtúr inmheánach an tábla.

Tá API Resources a thuigbheáil — conas a dhéanann siad cruth JSON, an buntáiste slándála a bhaineann le rialú réimsí go soiléir, agus gnéithe cosúil le réimsí coinníollach agus acmhainní neadaithe — ábhairín tábhachtach ar leith do APIs gairmiúla Laravel a thógáil, ó tharla go bhfuil miodlanna amh a nochtadh ní amháin contúirteach ach droch-dhearadh freisin.

De bharr go bhfuil APIs REST/JSON mar phríomh-úsáid Laravel inniu, agus dá bhfuil rialú ar chruth an fhreagairt (go sábháilte agus go geal) ina riachtanas coitianta, tábhachtach, is ionann API Resources agus uirlis a úsáidtear go minic, luachmhar a dhéanann idirdhealú idir APIs dea-thógtha, slán agus iad siúd nach bhfuil sonraí leigthe amach nó ceangailte go geal don bhunachair sonraí.