[PHP API] REST API 구축 시 자주 하는 실수 5가지

REST API를 만들 땐 작은 실수가 큰 보안 이슈나 버그로 이어질 수 있습니다. 지금 점검해보세요!

안녕하세요! 저는 처음 PHP로 REST API를 만들 때, GET과 POST만 쓰고 나머지는 몰라서 무시했었어요. JSON도 그냥 echo로 보내고, 상태 코드는 신경 안 썼죠. 근데 시간이 지나면서, 이런 사소한 실수가 나중에 보안 구멍이 되거나 클라이언트에서 응답을 제대로 못 받는 문제로 이어지더라고요. 특히 실무에서 API는 백엔드의 얼굴이기 때문에 더 세심한 설계와 구현이 필요합니다. 이 글에서는 제가 겪었던 시행착오와, 초보자분들이 흔히 놓치는 실수 5가지를 뽑아서 자세히 설명드릴게요. 한 번쯤 겪었거나 앞으로 겪을 수도 있는 실수들이니 꼭 참고해보세요!

목차

1. HTTP 메서드 구분 없이 모든 요청 처리 2. JSON Content-Type 누락 또는 오설정 3. 응답 코드 생략 또는 잘못된 반환 4. 인증 없이 민감 정보 노출 5. URI에 동사를 넣는 비RESTful 설계 6. 실수 방지를 위한 체크리스트 요약

1. HTTP 메서드 구분 없이 모든 요청 처리

PHP에서는 $_GET, $_POST만으로 요청을 처리하는 경우가 많아요. 하지만 REST API에서는 GET, POST, PUT, DELETE 등 HTTP 메서드를 명확히 구분해서 처리해야 합니다.

$method = $_SERVER['REQUEST_METHOD'];

if ($method === 'GET') {
  // 조회
} elseif ($method === 'POST') {
  // 생성
} elseif ($method === 'PUT') {
  // 수정
} elseif ($method === 'DELETE') {
  // 삭제
}

switch-case나 if-else로 메서드별 분기 처리를 하지 않으면 API 동작이 뒤엉켜버리고, 클라이언트도 혼란스러워집니다.

2. JSON Content-Type 누락 또는 오설정

클라이언트와 서버 간 데이터는 대부분 JSON 포맷으로 주고받기 때문에, 헤더 설정이 매우 중요합니다. 누락되면 클라이언트가 데이터를 해석하지 못하거나 CORS 오류가 발생할 수도 있어요.

올바른 설정	잘못된 설정
Content-Type: application/json	text/html, 누락됨
Accept: application/json	application/x-www-form-urlencoded

// PHP 응답 시 반드시 포함
header('Content-Type: application/json; charset=utf-8');

728x90

3. 응답 코드 생략 또는 잘못된 반환

REST API에서는 단순히 JSON만 보내는 게 아니라, HTTP 상태 코드를 함께 반환해 요청 결과를 명확히 알려줘야 해요. 상태 코드가 없으면 프론트에서는 무조건 “성공”으로 받아들일 수 있어요.

• 200 OK - 정상 처리
• 201 Created - 생성 완료
• 400 Bad Request - 잘못된 입력
• 401 Unauthorized - 인증 실패
• 404 Not Found - 리소스 없음

http_response_code(201);
echo json_encode(['message' => '사용자가 등록되었습니다']);

4. 인증 없이 민감 정보 노출

초보 API 개발자가 가장 자주 하는 실수 중 하나는 인증 없이 중요한 정보를 노출하는 것입니다. 예를 들어 /users API가 로그인 없이 누구나 접근 가능하면 개인정보가 그대로 노출될 수 있어요.

이런 경우에는 반드시 API 토큰 인증이나 세션 기반 보호를 통해 권한 검사를 수행해야 합니다.

$headers = getallheaders();
$token = $headers['Authorization'] ?? '';

if ($token !== 'Bearer your-secret-token') {
  http_response_code(401);
  echo json_encode(['error' => '인증 실패']);
  exit;
}

간단한 예제에서는 위처럼 토큰 문자열만 비교해도 되지만, 실제 환경에서는 JWT 기반 인증, 세션 기반 권한 분기, OAuth 등 보다 안전한 방식이 필요합니다.

 

PHP preg_match() 함수로 패턴 검사하기

5. URI에 동사를 넣는 비RESTful 설계

RESTful 설계의 핵심은 URI는 명사로 표현하고, 동작은 HTTP 메서드로 구분하는 것입니다. 그런데 초보자들이 자주 /getUser, /deleteUser처럼 URI에 동사를 섞는 실수를 해요.

비RESTful 방식	RESTful 방식
/getUser	GET /users/1
/deleteUser	DELETE /users/1
/createUser	POST /users

URL은 자원(Resource)을 표현하는 명사로 만들고, 작업은 HTTP 메서드로 구분하는 습관을 들이세요. 이게 REST API의 본질이에요!

6. 실수 방지를 위한 체크리스트 요약

아래는 PHP로 REST API를 개발할 때 자주 발생하는 실수들을 방지하기 위한 핵심 체크리스트입니다. API 개발 전에 한 번씩 꼭 점검해보세요!

• HTTP 메서드를 $_SERVER['REQUEST_METHOD']로 구분하고 각각 분기 처리했는가?
• JSON 응답 시 Content-Type: application/json을 정확히 지정했는가?
• 응답 코드는 상황에 따라 200, 201, 400 등 올바르게 설정했는가?
• API 인증 없이 민감 데이터를 노출하고 있진 않은가?
• URI에 동사가 아닌 명사를 사용하고 있는가?

이 체크리스트만 잘 지켜도 80% 이상의 실수는 사전에 예방할 수 있어요. 작은 습관이 큰 품질 차이를 만듭니다. 🙂

 

저도 처음 REST API를 만들었을 때는 뭔가 "POST로만 보내면 되는 거 아냐?" 같은 생각으로 시작했어요. 그런데 프로젝트가 커지고, 프론트엔드와 협업이 들어가면서 메서드 구분, 응답 코드, 인증, URI 구조 등 정말 꼼꼼하게 맞춰야 할 것들이 생기더라고요. 특히 GET 요청으로 사용자 전체 목록이 그냥 노출된다거나, Content-Type을 안 줘서 클라이언트에서 JSON이 안 읽히는 경우엔 실제로 민망한 상황도 많이 겪었습니다. 😅 이번 글에서 소개한 실수들은 정말 많이 반복되는 것들이니, 꼭 한 번 실무 전에 점검해보시길 추천드려요. 사소한 것 같지만, 이런 디테일들이 진짜 API 퀄리티를 결정하더라고요!