PHP 프레임워크 – Laravel – 7 – API 개발

작성자 wooah
PHP 프레임워크 - Laravel - 7 - API 개발
PHP 프레임워크 – Laravel – 7 – API 개발

PHP 프레임워크 – Laravel – API 개발

안녕하세요 여러분~ 😊
이번 시간에는 Laravel을 이용한 API 개발 방법에 대해 소개해드릴게요!
최근에는 웹 서비스뿐만 아니라, **모바일 앱, 프론트엔드 SPA(Vue, React 등)**와 데이터를 주고받기 위해 RESTful API 개발이 매우 중요해졌죠!

Laravel은 이러한 API를 만들기에 정말 좋은 프레임워크예요.
간단하면서도 강력한 라우팅, Eloquent ORM, 리소스 클래스, 미들웨어, 토큰 인증 등…
모든 기능이 이미 완비되어 있어서 손쉽게 시작할 수 있답니다 💪

API란 무엇인가요?

💡 비유하자면?

API는 마치 레스토랑의 주문 시스템과 같아요.
우리는 메뉴판(API 명세)을 보고 주문(요청)을 하고,
서버는 그에 맞는 요리를 만들어서 JSON으로 반환(응답)해주는 거죠! 🍜

1. API 전용 라우트 정의 (routes/api.php)

Laravel에서는 API 전용 라우트를 따로 분리해서 관리할 수 있어요.

✅ 예: routes/api.php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Api\PostController;

Route::get('/posts', [PostController::class, 'index']);
Route::get('/posts/{id}', [PostController::class, 'show']);
Route::post('/posts', [PostController::class, 'store']);
Route::put('/posts/{id}', [PostController::class, 'update']);
Route::delete('/posts/{id}', [PostController::class, 'destroy']);

이 파일의 라우트는 모두 /api 접두어로 자동 접속됩니다. (예: /api/posts)

2. 컨트롤러 생성

API용 컨트롤러를 따로 만들 수도 있어요!

php artisan make:controller Api/PostController --api

--api 옵션은 RESTful에 필요한 메서드만 생성해줍니다:

  • index() : 목록 조회
  • show($id) : 단일 항목 조회
  • store() : 생성
  • update($id) : 수정
  • destroy($id) : 삭제

3. JSON 응답 반환

API는 브라우저에 HTML을 보여주는 게 아니라,
JSON 형식으로 데이터를 반환해야 해요.

public function index()
{
    return response()->json(Post::all());
}

response()->json()은 데이터를 JSON 포맷으로 변환해서 응답해줘요.

4. 데이터 생성 (POST 요청 처리)

public function store(Request $request)
{
    $validated = $request->validate([
        'title' => 'required|max:255',
        'content' => 'required',
    ]);

    $post = Post::create($validated);

    return response()->json($post, 201);
}

성공적으로 생성되었을 때는 HTTP 상태코드 201을 반환하는 게 좋아요!

5. API 리소스(Resource) 클래스

Laravel은 데이터를 더 깔끔하고 구조적으로 포장해서 전달할 수 있는
Resource 클래스도 제공합니다.

php artisan make:resource PostResource
public function toArray($request)
{
    return [
        'id' => $this->id,
        'title' => $this->title,
        'content' => $this->content,
        'created_at' => $this->created_at->toDateTimeString(),
    ];
}

컨트롤러에서 이렇게 사용해요:

use App\Http\Resources\PostResource;

public function show($id)
{
    $post = Post::findOrFail($id);
    return new PostResource($post);
}

6. API 요청 유효성 검사

폼처럼 validate()를 통해 요청 값을 검증할 수 있어요.

$request->validate([
    'title' => 'required|string|max:255',
    'content' => 'required',
]);

에러가 나면 JSON으로 자동 응답이 갑니다:

{
  "message": "The given data was invalid.",
  "errors": {
    "title": ["The title field is required."]
  }
}

7. 인증된 사용자만 접근하도록 제한하기

API는 토큰 인증 방식이 일반적이에요.

Laravel은 기본적으로 Sanctum, Passport 등의 토큰 기반 인증을 제공합니다.
여기서는 간단한 Sanctum을 사용해볼게요!

Sanctum 설치

composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate

app/Http/Kernel.php에 다음을 추가:

'api' => [
    \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
    'throttle:api',
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
],

User 모델에 HasApiTokens 트레잇 추가:

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, ...;
}

토큰 발급하기

public function login(Request $request)
{
    $user = User::where('email', $request->email)->first();

    if (!$user || !Hash::check($request->password, $user->password)) {
        return response()->json(['message' => '인증 실패'], 401);
    }

    return response()->json([
        'token' => $user->createToken('api-token')->plainTextToken,
    ]);
}

8. 토큰으로 API 요청하기

요청 헤더에 아래처럼 설정해 주세요:

Authorization: Bearer {발급받은_토큰}

auth:sanctum 미들웨어를 라우트에 걸어주면 인증된 사용자만 접근 가능해요.

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

9. 상태 코드 정리

코드 의미
200 OK 성공적인 요청
201 Created 생성 성공
204 No Content 삭제 성공 (응답 없음)
400 Bad Request 잘못된 요청
401 Unauthorized 인증 실패
403 Forbidden 권한 없음
404 Not Found 리소스 없음
422 Unprocessable Entity 유효성 오류

주의할 점 ✅

항목 주의사항
CORS 설정 다른 도메인에서 요청할 경우 반드시 설정 필요 (config/cors.php)
POSTMAN 테스트 토큰, 헤더 설정 주의해서 확인
토큰 노출 방지 토큰은 클라이언트에서 안전하게 저장 (예: LocalStorage, Cookies)
예외 처리 try-catch 또는 커스텀 예외 핸들링 활용하기
라우트 그룹화 prefix, middleware로 API 버전 관리가 유용해요 (/api/v1/...)

요약 정리 🎯

항목 설명
API 라우트 routes/api.php에 정의 (자동으로 /api 접두어)
JSON 응답 response()->json() 또는 Resource 사용
유효성 검사 validate() 사용 가능, 에러는 JSON으로 자동 반환
인증 처리 Laravel Sanctum을 사용하여 토큰 기반 인증 구현
상태 코드 REST 규약에 따라 적절히 사용해야 클라이언트도 이해하기 쉬움

마무리하며 😊

Laravel을 이용한 API 개발은 간결하면서도 강력하고, 보안까지 고려된 구조를 쉽게 구현할 수 있게 도와줍니다.
단순한 CRUD부터 시작해서 인증, 권한, 에러 처리까지 완벽한 백엔드 API 서버를 만들 수 있어요!

다음 시간에는 API 테스트, 버전 관리, 에러 핸들링 전략까지도 이어서 알려드릴게요!
그럼 오늘도 Laravel과 함께 믿음직한 API를 멋지게 만들어보세요~ 💻📱🚀

답글 남기기