[PHP API] 실무에 강한 REST API 개발법 총정리

이제는 단순 API가 아닌, 실무에 바로 적용 가능한 PHP REST API를 만들어야 할 때입니다.

안녕하세요! 예전에는 PHP로 API를 만든다고 하면 단순히 GET, POST 요청에 대한 응답만 처리하는 정도였어요. 하지만 지금은 프론트엔드와의 완벽한 분리, 모바일 앱 연동, 외부 API 제공 등 복잡하고 정교한 REST API가 요구되는 시대입니다. 특히 실무에서는 응답 속도, 인증 보안, 오류 처리, 구조화된 폴더 설계, 테스트 코드까지 고려해야 하죠.

이번 글에서는 단순한 REST 개념을 넘어서, 진짜 현업에서 바로 써먹을 수 있는 실전 위주의 PHP REST API 개발 전략을 총정리해드립니다. 구조부터 보안, 프레임워크 활용까지 차근차근 짚어볼게요.

목차

1. 실무에서 REST API가 필요한 이유 2. 디렉토리 구조와 파일 분리 전략 3. 라우팅 처리와 메서드 분기 구현 4. 인증 시스템(JWT/토큰 기반) 구축 5. 예외 처리와 에러 응답 설계 6. 실무 활용을 위한 확장 포인트 요약

1. 실무에서 REST API가 필요한 이유

프론트엔드와 백엔드가 완전히 분리된 구조가 보편화되면서, REST API는 웹/앱 개발에서 필수가 되었습니다. 실무에서는 다음과 같은 이유로 REST API를 사용합니다.

• 프론트(Vue, React 등)와 백엔드 간 데이터 통신
• 모바일 앱(Android/iOS)과의 통신
• 외부 파트너/제휴사에 API 제공
• 헤드리스 CMS, SPA, 마이크로서비스 환경에 필수

REST API는 단순히 “서버 데이터 보여주기”를 넘어서, 서비스 전체의 설계와 확장성을 좌우하는 중요한 축입니다.

2. 디렉토리 구조와 파일 분리 전략

실무에서는 기능별로 파일을 분리하고, 유지보수가 쉬운 구조를 구성해야 합니다. 하나의 index.php에 모든 로직을 넣는 방식은 매우 위험해요.

폴더	설명
/api	라우팅과 요청 분기 처리
/controllers	API별 기능 로직 구현
/models	DB 처리 및 쿼리 모듈화
/middleware	토큰 인증, 권한 검사 등
/utils	공통 함수, 에러 핸들러

이런 구조는 라우팅 → 인증 → 컨트롤러 → 모델 순의 깔끔한 흐름을 만들고, 팀 개발에서도 협업이 쉬워집니다.

728x90

3. 라우팅 처리와 메서드 분기 구현

PHP로 REST API를 만들 때는 요청 URL과 메서드를 기반으로 적절한 컨트롤러로 연결해야 합니다. 이를 위해 간단한 라우터 클래스를 구현할 수도 있고, Slim, FlightPHP 같은 라이트 프레임워크를 사용할 수도 있어요.

• $_SERVER['REQUEST_URI']로 URI 분석
• $_SERVER['REQUEST_METHOD']로 메서드 확인
• switch-case 또는 Router 클래스로 분기 처리

if ($uri === '/users' && $method === 'GET') {
  require 'controllers/user.list.php';
} elseif ($uri === '/users' && $method === 'POST') {
  require 'controllers/user.create.php';
}

이런 구조화된 분기는 추후 유지보수와 테스트에서도 큰 차이를 만들어냅니다.

4. 인증 시스템(JWT/토큰 기반) 구축

실무 API는 인증 없이 절대 운영되지 않습니다. 특히 REST API는 상태 정보를 서버가 기억하지 않기 때문에, 토큰 기반 인증을 주로 사용합니다. 가장 대표적인 방식이 JWT (JSON Web Token)입니다.

사용 흐름은 아래와 같습니다:

• 사용자가 로그인 시 서버에서 JWT를 발급
• 클라이언트는 이후 모든 요청 헤더에 JWT 포함
• 서버는 Authorization: Bearer {token}로부터 인증 처리

$headers = getallheaders();
$auth = $headers['Authorization'] ?? '';
$token = str_replace('Bearer ', '', $auth);

if (!validateJWT($token)) {
  http_response_code(401);
  echo json_encode(['error' => '인증되지 않은 요청']);
  exit;
}

JWT는 PHP에서 firebase/php-jwt 라이브러리로 쉽게 구현 가능합니다. 실무에선 반드시 토큰 만료, 리프레시 토큰, 권한 레벨까지 고려해야 합니다.

 

PHP로 HTTP 응답에서 XML 데이터만 파싱하는 방법

5. 예외 처리와 에러 응답 설계

API에서 에러는 무조건 발생합니다. 중요한 건 에러를 어떻게 예쁘게, 구조적으로 클라이언트에게 전달하느냐입니다. 그냥 die("에러") 하는 방식은 이제 그만!

상황	응답 예시
필수 파라미터 누락	HTTP 400 + {"error":"email은 필수 항목입니다"}
인증 실패	HTTP 401 + {"error":"인증 토큰이 유효하지 않습니다"}
서버 내부 오류	HTTP 500 + {"error":"서버 오류. 잠시 후 다시 시도하세요"}

에러 메시지는 사용자가 이해할 수 있게, 응답 형식도 항상 JSON으로 통일하는 것이 실무의 기본입니다.

6. 실무 활용을 위한 확장 포인트 요약

• 쿼리 파라미터로 페이징, 정렬, 검색 구현
• CORS 헤더 추가로 클라이언트 연동 허용
• 버전 관리를 위해 /v1, /v2와 같은 엔드포인트 도입
• 로깅 시스템으로 에러/요청 기록 저장
• API 문서화를 위해 Swagger 또는 JSON 스펙 정의

이 포인트들을 정리해두면 추후 유지보수, 협업, API 외부 제공 시 훨씬 수월해집니다. PHP도 충분히 강력한 REST 백엔드가 될 수 있어요!

 

Q PHP로 만든 REST API도 모바일 앱과 연동할 수 있나요?

네, 물론 가능합니다! 실제로 많은 중소 프로젝트에서 PHP 기반 REST API가 앱 백엔드로 사용됩니다. JSON 응답만 잘 맞춰주면 Android, iOS 모두 연동에 문제없어요.

A 네! JSON만 잘 맞추면 앱 연동에 전혀 문제 없습니다.

Q JWT를 꼭 써야 하나요? 세션 기반 인증은 안 되나요?

세션 기반도 가능합니다. 하지만 REST API는 Stateless(무상태) 특성이 있으므로, 토큰 기반 인증이 더 잘 어울립니다. 특히 모바일, 외부 서비스 연동에는 JWT가 표준처럼 사용돼요.

A 세션도 가능하지만, 실무에선 JWT가 더 유리해요.

Q CORS 에러가 나는데 PHP에서 해결할 수 있나요?

네, PHP에서 헤더를 추가해 해결할 수 있습니다. header("Access-Control-Allow-Origin: *")을 응답에 포함시키면 다른 도메인에서도 API 호출이 가능해집니다. 실제 서비스에선 * 대신 도메인을 명시하세요.

A CORS는 PHP에서 헤더 설정으로 쉽게 해결 가능해요!

Q Slim 같은 PHP 마이크로 프레임워크는 꼭 써야 하나요?

꼭은 아니지만 실무에선 강력 추천됩니다. 라우팅, 에러 처리, 미들웨어 등이 구조화돼 있어 개발 속도와 유지보수성이 훨씬 좋아져요. 순수 PHP보단 Slim, FlightPHP 등을 추천드려요.

A 구조적인 API를 원한다면 마이크로 프레임워크는 필수!

Q API 요청에 대한 로그는 꼭 남겨야 하나요?

네! 실시간 문제 파악이나 보안 이슈 추적을 위해 모든 요청을 로깅하는 것이 매우 중요합니다. 날짜별 로그 파일, 에러 코드, 응답 시간 등을 기록하면 실무에서 큰 도움이 됩니다.

A 실무에서는 로그가 생명입니다! 꼭 남기세요.

PHP json_encode() 함수로 json으로 변환하기

 

저는 처음 REST API를 구현할 때, 파일 하나에 모든 로직을 다 때려 넣고 겨우겨우 동작만 시켰던 기억이 있어요. 😅 하지만 실제 서비스를 운영하다 보니, 구조화의 중요성이 절실해지더라고요. 디렉토리 나누고, 라우팅 처리하고, 인증도 따로 분리해서 JWT 붙이고, 요청마다 로깅까지… 점점 API가 ‘서비스’처럼 변해갔어요. 이번 글은 그런 실무 경험을 바탕으로 정리한 실전 노하우 모음입니다. 여러분도 단순한 “동작 확인용 API”를 넘어서, 프론트와 협업 가능한, 운영 가능한 구조로 만들어보세요. PHP도 충분히 강력하고 실용적인 백엔드 언어라는 걸 직접 느끼실 수 있을 거예요!