API Resource란 무엇인가요?

Question

Accepted Answer

**API Resource**는 Eloquent 모델(과 컬렉션)이 API 응답을 위해 **JSON으로 직렬화되는** 방식을 제어하는 변환 클래스입니다. API 출력을 정밀하게 형성할 수 있게 해줍니다 — 어떤 필드를 노출할지 선택하고, 이름을 바꾸고, 값을 포맷하며, 연관 데이터를 포함시켜 — API 표현을 데이터베이스 구조에서 분리합니다.

## 문제: 원시 모델 노출

```php
// ❌ 모델을 직접 반환하면 모든 컬럼이 노출됨 (민감한 것 포함 가능)
return User::find($id);   // { id, name, email, password_hash, internal_notes, ... } 😱
```

## 해결책: 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와 내부 필드는 의도적으로 생략됨
            'joined' => $this->created_at->toDateString(),   // 값 포맷
            'is_admin' => (bool) $this->is_admin,
            // 연관 데이터 포함 (조건부 로딩)
            'posts' => PostResource::collection($this->whenLoaded('posts')),
        ];
    }
}
```

```php
// 컨트롤러에서 사용
return new UserResource($user);                  // 단일 모델
return UserResource::collection(User::all());     // 컬렉션
```

resource의 `toArray()`는 정확한 JSON 형태를 정의합니다 — 어떤 필드가 나타날지 제어하고, 이름을 바꾸고 포맷하며, 연관된 resource를 포함시킵니다. 민감한 필드는 단순히 포함하지 않습니다.

## 조건부 및 중첩 데이터

```php
return [
    'id' => $this->id,
    'secret' => $this->when($request->user()->isAdmin(), $this->secret),  // 조건부 필드
    'posts' => PostResource::collection($this->whenLoaded('posts')),       // 즉시 로딩된 경우에만
];
```

## 왜 중요한가

API Resource는 Laravel에서 잘 설계되고 안전한 API를 구축하는 데 중요합니다 — JSON 출력을 정밀하게 제어하게 해주며, 이는 **보안**과 API 설계 모두에 중요합니다.

가장 결정적인 이점은 **데이터 유출 방지**입니다: Eloquent 모델을 직접 반환하면 모든 컬럼(잠재적으로 비밀번호 해시, 내부 플래그, 기타 민감한 데이터 포함 — 심각한 취약점)이 노출되는 반면, API Resource는 어떤 필드를 노출할지 명시적으로 선택하게 하여 민감한 데이터가 클라이언트에 절대 도달하지 않도록 보장합니다.

보안을 넘어, **API 표현을 데이터베이스 스키마에서 분리**하여 깔끔한 API 설계를 가능하게 합니다 — 필드 이름 변경, 값 포맷(날짜, 불리언), 중첩/연관 데이터 구조화, 권한에 따른 조건부 필드 포함을 모두 전용 변환 클래스에서 할 수 있습니다.

이는 API 계약을 내부 테이블 구조에 결합하기보다 안정적이고 의도적으로 유지합니다.

API Resource — JSON 출력을 어떻게 형성하는지, 명시적 필드 제어의 보안 이점, 조건부 필드와 중첩 resource 같은 기능 — 를 이해하는 것은 전문적인 Laravel API를 구축하는 데 중요한 지식입니다. 원시 모델을 노출하는 것은 안전하지 않고 설계도 좋지 않기 때문입니다.

REST/JSON API가 오늘날 Laravel의 주요 용도이고, (안전하고 깔끔하게) 응답 형태를 제어하는 것이 일반적이고 중요한 요구이므로, API Resource는 데이터를 유출하거나 출력을 데이터베이스에 강하게 결합하는 API와 잘 구축되고 안전한 API를 구별하는, 자주 사용되는 가치 있는 도구입니다.