RESTful API 설계 원칙과 구현

모던 백엔드 개발에서 REST(REpresentational State Transfer) 원칙은 선택이 아닌 필수입니다. URI(주소)로는 조작할 자원(Resource)만을 명시하고, 그 자원에 대해 '어떤 행동(Action)'을 할 것인지는 HTTP Method(GET, POST, PUT, DELETE)로 정의하는 이 우아한 표준 설계 패턴을 Slim 프레임워크에 구현하는 방법을 알아봅니다.

1. 안 좋은 API 설계 vs RESTful API 설계

과거에는 URI 자체에 동사(행위)를 포함시키는 경우가 많았습니다. (예: /createUser). REST 아키텍처에서는 주소는 명사형 자원(/users)만 명시하고, CRUD 행위는 HTTP Method에 전적으로 위임합니다.

행위 (CRUD)	안 좋은 예시 (동사 포함)	RESTful 예시 (표준)
목록 조회 (Read)	GET /getUsers	GET /users
신규 생성 (Create)	POST /createUser	POST /users
전체 수정 (Update)	POST /updateUser?id=7	PUT /users/7
레코드 삭제 (Delete)	GET /deleteUser?id=7	DELETE /users/7

2. Slim 프레임워크에서의 라우팅 그룹핑(Grouping)

Slim 프레임워크는 HTTP Method별로 직관적인 라우팅 메서드(get, post, put, delete)를 제공합니다. 또한 $app->group()을 활용하면 동일한 경로(/users)를 사용하는 연관된 API들을 깔끔하게 묶어(Grouping) 코드를 구조화할 수 있습니다.

      
      routes.php
    

<?php
use Slim\Routing\RouteCollectorProxy;

// '/users' 공통 경로를 묶는 그룹 설정
$app->group('/users', function (RouteCollectorProxy $group) {
    
    // [C] 생성: POST /users
    $group->post('', function ($request, $response) {
        $data = $request->getParsedBody();
        // DB 저장 로직 (Eloquent 등)
        return $response->withStatus(201); // 상태코드 201 Created 반환
    });

    // [R] 목록 조회: GET /users
    $group->get('', function ($request, $response) {
        $users = ["user1", "user2"];
        $response->getBody()->write(json_encode($users));
        return $response->withHeader('Content-Type', 'application/json')->withStatus(200);
    });

    // [R] 단일 조회: GET /users/{id}
    $group->get('/{id}', function ($request, $response, $args) {
        // $args['id'] 로 대상 유저 식별
        return $response->withStatus(200);
    });

    // [U] 통째로 수정: PUT /users/{id}
    $group->put('/{id}', function ($request, $response, $args) {
        return $response->withStatus(200);
    });

    // [D] 삭제: DELETE /users/{id}
    $group->delete('/{id}', function ($request, $response, $args) {
        return $response->withStatus(204); // 성공했으나 돌려줄 바디 내용이 없다는 뜻 (204 No Content)
    });
    
});
?>

Terminal (curl API Testing)

$ curl -i -X POST http://localhost:8080/users -d '{"name":"Charlie"}'
HTTP/1.1 201 Created
Host: localhost:8080
Content-Length: 0
Date: Fri, 22 May 2026 09:05:12 GMT
$ curl -i -X DELETE http://localhost:8080/users/7
HTTP/1.1 204 No Content
Host: localhost:8080
Date: Fri, 22 May 2026 09:05:18 GMT

💡 적절한 HTTP 상태 코드(Status Code) 반환

완벽한 REST API를 구축하려면 응답 바디(JSON 데이터)뿐만 아니라, HTTP 헤더의 상태 코드도 상황에 맞게 명확히 응답해야 합니다. 데이터 생성 성공 시에는 201 Created, 데이터 삭제 완료 후 바디 내용이 비어있을 때는 204 No Content, 인증되지 않은 요청엔 401 Unauthorized를 반환하는 것이 글로벌 표준 설계입니다.

API 응답 상태 코드 확인

위의 터미널 목업에서는 curl을 이용해 API를 테스트한 결과를 보여줍니다. 동일한 자원 URI(/users)를 대상으로 하더라도 서로 다른 HTTP Method(POST, DELETE)를 요청했을 때 백엔드 라우터가 이를 분기하여 적절한 처리 후 알맞은 상태 코드(201 Created, 204 No Content)를 응답하는 것을 확인할 수 있습니다.

행위 (CRUD)

안 좋은 예시 (동사 포함)

RESTful 예시 (표준)

목록 조회 (Read)

GET /getUsers

GET /users

신규 생성 (Create)

POST /createUser

POST /users

전체 수정 (Update)

POST /updateUser?id=7

PUT /users/7

레코드 삭제 (Delete)

GET /deleteUser?id=7

DELETE /users/7

<?php use Slim\Routing\RouteCollectorProxy; // '/users' 공통 경로를 묶는 그룹 설정 $app->group('/users', function (RouteCollectorProxy $group) { // [C] 생성: POST /users $group->post('', function ($request, $response) { $data = $request->getParsedBody(); // DB 저장 로직 (Eloquent 등) return $response->withStatus(201); // 상태코드 201 Created 반환 }); // [R] 목록 조회: GET /users $group->get('', function ($request, $response) { $users = ["user1", "user2"]; $response->getBody()->write(json_encode($users)); return $response->withHeader('Content-Type', 'application/json')->withStatus(200); }); // [R] 단일 조회: GET /users/{id} $group->get('/{id}', function ($request, $response, $args) { // $args['id'] 로 대상 유저 식별 return $response->withStatus(200); }); // [U] 통째로 수정: PUT /users/{id} $group->put('/{id}', function ($request, $response, $args) { return $response->withStatus(200); }); // [D] 삭제: DELETE /users/{id} $group->delete('/{id}', function ($request, $response, $args) { return $response->withStatus(204); // 성공했으나 돌려줄 바디 내용이 없다는 뜻 (204 No Content) }); }); ?>