API რესურსები

არ დააბრუნოთ raw Eloquent დატა API response-ში. ყოველთვის გამოიყენეთ API რესურსები.

API რესურსი არის transformation layer თქვენს Eloquent models-სა და JSON response-ს შორის.

წარმოიდგინეთ, რომ თქვენი database არის სამზარეულო, სადაც ნედლი პროდუქტებია (raw data). API Resource არის მზარეული, რომელიც ამ პროდუქტებს ამზადებს და ლამაზად წარმოადგენს სტუმრებისთვის.

Laravel-ში (და API-ებში ზოგადად), raw models/arrays-ის დაბრუნება მუშაობს, მაგრამ API Resources-ის გამოყენება ითვლება საუკეთესო პრაქტიკად რამდენიმე მიზეზის გამო.

1. თქვენ აკონტროლებთ რა გადის თქვენი სისტემიდან

Raw Eloquent მოდელი ყველაფერს შეიცავს, რისგანაც იგი შედგება.

return User::find(1);

ეს შეიძლება შეიცავდეს :

• internal ID-ებს

• foreign key-ებს

• pivot data

• timestamps

• მომავალში დამატებული column-ებს

Resource-ით:

class UserResource extends JsonResource {
    public function toArray($request) {
        return [
            'id'   => $this->id,
            'name' => $this->name,
        ];
    }
}

✅ მხოლოდ წინასწარ განსაზღვრული დატა ❌ Database სტრუქტურა ≠ API contract

2. გამოყოფს API-ს database-ისგან

თქვენი ბაზის სქემა შეიცვლება. თქვენი API არ უნდა გაფუჭდეს ამის გამო.

თუ დააბრუნებთ raw model-ს, column-ის დამატება გაუთვალისწინებლად შეცვლის რისფონსს.

API რესურსი მოქმედებს როგორც სტაბილური API layer.

3. Conditional fields & relationships

რესურსები გაძლევთ საშუალებას დააბრუნოთ მონაცემები მხოლოდ საჭიროების შემთხვევაში.

return [
    'email' => $this->when($request->user()->isAdmin(), $this->email),
    'posts' => PostResource::collection($this->whenLoaded('posts')),
];

ეს შეუძლებელია (ან ძალიან ცუდია/არაპრაქტიკულია) raw models-ით.

4. უცვლელი response სტრუქტურა

Resources გაძლევთ:

• პროგნოზირებად JSON structure-ს

• ცვლადის უცვლელ სახელებს

• ცენტრალიზებულ formatting-ს

მაგალითად: თარიღები, enum-ები, გამოთვლილი ველები, fallback მნიშვნელობები.

როდესაც model-ს აბრუნებთ, თქვენ აბრუნებთ ყველაფერს, რაც იმ მომენტში ჩატვირთულია. ეს ნიშნავს, რომ database სტრუქტურა, internal ველები და მომავალში დამატებული ქოლუმნები შეიძლება "გაიპაროს" response-ში. ერთმა დამატებულმა column-მა ან relationship-მა შეიძლება ჩუმად შეცვალოს თქვენი API output.

Resource-ის შექმნა

php artisan make:resource UserResource

ეს შექმნის ფაილს: app/Http/Resources/UserResource.php

როგორ გამოიყურება რესურსის კლასი:

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    /**
     * გარდაქმნის model-ს array-ში.
     */
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'joinedDate' => $this->created_at->format('d.m.Y'),
            
            // Conditional field - მხოლოდ admin-ებს უჩანთ
            'role' => $this->when($request->user()->isAdmin(), $this->role),
        ];
    }
}

მაგალითი

// ❌ ცუდი
return User::find($id);
// აბრუნებს: id, name, email, password (თუ hidden არ არის მოდელის კლასში), remember_token, created_at, updated_at, 
// და ნებისმიერ სხვა column-ს რაც დაამატეთ

// ✅ კარგი
return new UserResource(User::find($id));

class UserResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            // მხოლოდ ეს - არაფერი მეტი, არაფერი ნაკლები
        ];
    }
}

შეჯამება ერთ წინადადებაში

API რესურსი არის კონტრაქტი თქვენს database-სა და გარე სამყაროს შორის — უსაფრთხო, სტაბილური და კონტროლირებადი.

მეტი ინფო ნახეთ ლარაველის დოკუმენტაციაში.