[PHP API] 백엔드 API 설계: REST 원칙부터 실습까지

단순한 기능 구현을 넘어, 원칙에 충실한 RESTful API를 PHP로 직접 만들어봅시다!

안녕하세요! 저는 API를 처음 만들었을 때 “일단 동작만 하면 되지”라는 생각으로 시작했었어요. 그런데 어느 순간부터 클라이언트 개발자와의 협업에서 계속 충돌이 생기고, URL은 지저분하고, 유지보수도 힘들어지더라고요. 결국 알게 된 게 바로 “RESTful 원칙”이었습니다. REST는 단순히 기술이 아니라 약속이에요. 이 글에서는 REST 아키텍처의 원칙을 바탕으로 PHP에서 직접 GET, POST, PUT, DELETE를 처리하며 백엔드 API를 설계하는 법을 다룹니다. 실습 코드와 함께 하나씩 만들어보며 원리를 익힐 수 있게 구성했어요. 이 글 하나면, 여러분의 API가 한 단계 진화하게 될 거예요!

목차

1. REST 아키텍처의 6가지 핵심 원칙 2. RESTful API를 위한 설계 규칙 3. PHP로 기본 API 로직 구현 4. 메서드별 분기와 JSON 응답 구조 5. 사용자 리소스 예제로 CRUD 실습 6. REST API 점검 체크리스트

1. REST 아키텍처의 6가지 핵심 원칙

REST는 Roy Fielding 박사가 제안한 웹 아키텍처 스타일로, 클라이언트와 서버 간의 상호작용을 구조화하는 원칙들을 따릅니다. 단순히 API를 만든다고 RESTful한 건 아닙니다. 다음 6가지 원칙을 충실히 따라야 합니다.

• Client-Server (클라이언트-서버 분리): UI와 데이터 처리 완전 분리
• Stateless (무상태성): 서버는 클라이언트의 상태를 저장하지 않음
• Cacheable (캐시 처리): 응답은 캐시 가능 여부를 포함
• Uniform Interface (일관된 인터페이스): URI, 메서드, 응답 구조 통일
• Layered System (계층 구조): 중간 서버, 프록시 등을 통해 분산 가능
• Code on Demand (선택적 기능): 서버가 클라이언트에 코드를 전송할 수 있음 (거의 사용되지 않음)

이 원칙들을 고려하면서 설계해야 비로소 “RESTful”한 API라고 할 수 있어요.

2. RESTful API를 위한 설계 규칙

REST API의 설계에서 가장 중요한 건 URI 구조와 HTTP 메서드의 역할 분담입니다. 다음 표는 자주 사용하는 설계 규칙을 정리한 것입니다.

HTTP 메서드	URI 예시	동작 설명
GET	/users	전체 사용자 목록 조회
GET	/users/1	특정 사용자 정보 조회
POST	/users	새 사용자 생성
PUT	/users/1	1번 사용자 정보 수정
DELETE	/users/1	1번 사용자 삭제

URI에는 절대 동사를 넣지 않고, 자원 중심(명사형)으로 설계하는 것이 RESTful의 핵심입니다.

3. PHP로 기본 API 로직 구현

이제 PHP에서 실제 API를 만들어볼 차례입니다. 우선 index.php 하나로 메서드별 요청 분기를 처리하는 기본 틀을 잡아봅시다.

• GET: 목록 조회
• POST: 생성
• PUT: 수정
• DELETE: 삭제

$method = $_SERVER['REQUEST_METHOD'];

switch ($method) {
  case 'GET':
    echo json_encode(["method" => "GET"]);
    break;
  case 'POST':
    echo json_encode(["method" => "POST"]);
    break;
  case 'PUT':
    parse_str(file_get_contents("php://input"), $_PUT);
    echo json_encode(["method" => "PUT", "data" => $_PUT]);
    break;
  case 'DELETE':
    echo json_encode(["method" => "DELETE"]);
    break;
}

이 기본 구조를 확장해 실습에서는 사용자 리소스에 적용해볼 거예요!

4. 메서드별 분기와 JSON 응답 구조

REST API는 클라이언트와 데이터를 주고받기 때문에 JSON 형식의 응답과 적절한 HTTP 상태 코드를 반환하는 것이 핵심입니다. PHP에서는 아래와 같이 처리할 수 있어요.

header("Content-Type: application/json; charset=UTF-8");

$response = [
  "status" => "ok",
  "data" => [
    "id" => 1,
    "name" => "홍길동"
  ]
];

http_response_code(200);
echo json_encode($response, JSON_UNESCAPED_UNICODE);

또한, 요청에 따라 다른 JSON 구조를 반환하는 것이 클라이언트의 처리 효율성을 높입니다. 아래는 주요 메서드와 응답 형식 예시입니다.

HTTP 메서드	응답 예시
GET	{"users":[{"id":1,"name":"홍길동"}]}
POST	{"message":"생성 완료", "user":{...}}
PUT	{"message":"수정 성공"}
DELETE	{"message":"삭제 완료"}

 

PHP strtolower() 함수 - 문자열 소문자 변환

5. 사용자 리소스 예제로 CRUD 실습

실제 사용자 데이터를 대상으로 CRUD API를 만들어볼게요. 파일을 데이터 저장소로 사용하며, 실제 환경에서는 DB로 확장하면 됩니다.

• GET /users → 전체 사용자 목록
• POST /users → 새 사용자 추가
• PUT /users/1 → 사용자 정보 수정
• DELETE /users/1 → 사용자 삭제

// POST 예제
$input = json_decode(file_get_contents("php://input"), true);
$users = json_decode(file_get_contents("users.json"), true);
$input['id'] = time();
$users[] = $input;
file_put_contents("users.json", json_encode($users, JSON_UNESCAPED_UNICODE));
http_response_code(201);
echo json_encode(["message" => "생성 완료", "user" => $input]);

위 방식으로 각 메서드에 맞는 로직을 추가해주면 완성도 높은 사용자 API가 됩니다!

6. REST API 점검 체크리스트

• URI는 리소스 중심 명사형으로 설계했는가?
• 메서드는 GET/POST/PUT/DELETE로 명확히 구분되는가?
• 응답은 JSON 형식이며 Content-Type 설정이 되어 있는가?
• 에러 발생 시 http_response_code()로 상태를 명확히 표현했는가?
• CRUD 로직은 각 메서드에 분리되어 있는가?

이 체크리스트를 지키는 것만으로도, 여러분의 PHP API는 실무에서도 통하는 구조가 될 수 있어요!

 

PHP strtotime() 함수로 날짜를 타임스탬프로 변환

 

Q REST API에서 URI는 왜 동사가 아닌 명사여야 하나요?

REST에서는 URI가 자원을 표현해야 하기 때문에 명사로 작성하는 것이 원칙입니다. 동작은 HTTP 메서드(GET, POST 등)로 구분하므로 /getUser 같은 표현은 비RESTful이에요.

A URI는 '무엇'을 의미, 행동은 HTTP 메서드로! 이것이 REST의 기본이에요.

Q PHP에서 PUT이나 DELETE 요청 데이터를 어떻게 받나요?

PUT이나 DELETE 요청은 $_POST처럼 자동으로 수신되지 않기 때문에 php://input을 이용해 직접 입력 스트림을 읽어야 합니다. 그 후 json_decode() 등으로 파싱하죠.

A php://input으로 직접 읽고 json_decode()로 처리하세요!

Q GET과 POST 이외의 메서드는 브라우저에서 테스트가 안 되나요?

맞습니다. 브라우저 주소창이나 기본 HTML form에서는 GET과 POST만 지원합니다. PUT, DELETE 등은 Postman, curl, JS fetch 등을 사용해야 정상적으로 요청을 보낼 수 있어요.

A 테스트 도구를 써야 해요! Postman이 대표적입니다.

Q 응답이 JSON인지 아닌지는 어떻게 구분하나요?

서버에서 응답 헤더에 Content-Type: application/json을 설정해야 브라우저나 클라이언트가 JSON 데이터로 인식합니다. 이 설정이 없으면 text/html로 오인할 수 있어요.

A 반드시 Content-Type 헤더를 JSON으로 명시하세요!

Q REST API 응답에 HTML을 포함하면 안 되나요?

REST API는 데이터를 주고받는 것이 목적이므로 HTML은 포함하지 않는 것이 원칙입니다. 응답은 항상 구조화된 데이터(JSON 또는 XML)여야 하고, HTML은 뷰 레이어에서 처리해야 해요.

A REST 응답에는 HTML이 아닌 JSON만 담는 게 원칙입니다!

 

처음에는 단순히 URL로 데이터를 보내고 결과를 받는 게 전부라고 생각했어요. 그런데 REST를 이해하고, 메서드별로 역할을 나누고, 자원을 중심으로 URI를 설계하고, 에러 처리와 응답 포맷까지 신경 쓰기 시작하니 “이게 진짜 백엔드 개발이구나!”라는 생각이 들더라고요. 특히 클라이언트와 협업할 땐 이 정돈된 구조가 얼마나 큰 힘이 되는지 실감했어요. 이번 글이 여러분이 PHP로 백엔드 API를 더 깔끔하고 확장성 있게 만드는 데 도움이 되길 바라며, 작은 실습이라도 꼭 따라 해보시길 추천드립니다. 실력이 한 뼘 자라날 거예요!

 

PHP time() 함수 사용하기