[PHP API] REST API와 JSON 데이터 처리 기초부터 고급까지

REST API와 JSON 처리가 어렵게 느껴지셨나요? 이 글 하나로 기초부터 실습까지 한 번에 정리해드립니다!

안녕하세요! 저도 처음 PHP로 API를 만들었을 땐, JSON이 뭔지도 모르고 echo로 배열만 던졌던 기억이 납니다. 하지만 실제로 클라이언트와 통신하면서 구조화된 JSON 응답, 적절한 Content-Type 설정, 메서드 분리 등 기본기를 제대로 익혀야 하더라고요. 이 글에서는 PHP로 REST API를 만들면서 JSON 데이터를 쉽게 다루는 방법을 초보자의 눈높이에서 차근차근 알려드릴게요. 코드 실습을 중심으로 바로 따라 할 수 있게 구성했으니, 편하게 따라오세요!

목차

1. REST API와 JSON이란? 2. PHP에서 JSON 응답 처리 방법 3. PHP에서 JSON 요청 받기 4. JSON 기반 CRUD 실습 5. JSON 에러 메시지 처리 전략 6. REST + JSON 점검 체크리스트

1. REST API와 JSON이란?

REST API는 웹에서 데이터를 주고받기 위한 일종의 약속입니다. GET, POST, PUT, DELETE 같은 HTTP 메서드를 통해 서버와 클라이언트가 정해진 형식으로 소통하죠. 이때 가장 많이 쓰이는 데이터 포맷이 JSON입니다. JSON은 JavaScript Object Notation의 줄임말로, 사람도 읽기 쉽고 기계도 빠르게 처리할 수 있어요.

즉, REST는 ‘어떻게 요청할 것인가’, JSON은 ‘어떤 형식으로 주고받을 것인가’를 의미합니다. 둘은 백엔드 API 개발에서 뗄 수 없는 짝꿍이에요!

2. PHP에서 JSON 응답 처리 방법

PHP로 JSON을 응답할 때는 반드시 Content-Type 헤더를 application/json으로 지정해야 합니다. 그리고 배열을 json_encode()로 문자열화하여 전송합니다.

요소	설명
header()	응답 헤더 설정 (Content-Type 등)
json_encode()	PHP 배열을 JSON 문자열로 변환
http_response_code()	상태 코드 지정 (예: 200, 404, 500)

header('Content-Type: application/json; charset=utf-8');
http_response_code(200);

$data = [
  "status" => "success",
  "message" => "요청이 완료되었습니다",
  "user" => ["id" => 1, "name" => "홍길동"]
];

echo json_encode($data, JSON_UNESCAPED_UNICODE);

728x90

3. PHP에서 JSON 요청 받기

클라이언트가 JSON 데이터를 POST로 보낼 경우, PHP에서는 php://input을 통해 본문(raw body)을 읽어야 합니다. $_POST로는 안 들어와요!

• php://input 사용으로 본문 전체 읽기
• json_decode()로 배열로 변환
• 보안 위해 is_array(), isset() 체크 필수

$body = file_get_contents("php://input");
$data = json_decode($body, true);

if (!is_array($data)) {
  http_response_code(400);
  echo json_encode(["error" => "잘못된 JSON 요청입니다."]);
  exit;
}

$name = $data['name'] ?? '비회원';
echo json_encode(["message" => "$name님, 안녕하세요!"]);

4. JSON 기반 CRUD 실습

이제 실제로 JSON 데이터를 주고받으며 사용자 데이터를 생성하고 조회하는 간단한 CRUD API를 만들어보겠습니다. DB 없이 파일로 저장하는 방식으로 연습해볼게요.

// POST 요청 - 사용자 추가
$input = json_decode(file_get_contents("php://input"), true);
$users = json_decode(file_get_contents("users.json"), true) ?? [];

$newUser = [
  "id" => time(),
  "name" => $input["name"] ?? "이름없음"
];

$users[] = $newUser;
file_put_contents("users.json", json_encode($users, JSON_UNESCAPED_UNICODE));

http_response_code(201);
echo json_encode(["message" => "사용자가 추가되었습니다", "user" => $newUser]);

GET 요청으로 users.json을 읽으면 전체 목록을 보여줄 수 있고, PUT과 DELETE도 $_SERVER['REQUEST_METHOD']로 분기해 처리할 수 있어요.

• GET → 전체 사용자 조회
• POST → 사용자 추가
• PUT → 사용자 수정
• DELETE → 사용자 삭제

5. JSON 에러 메시지 처리 전략

REST API에서는 에러 메시지도 JSON으로 반환하는 것이 원칙입니다. 단순히 die("에러")가 아니라, 상태 코드와 함께 클라이언트가 읽을 수 있는 형식으로 응답해야 합니다.

에러 상황	JSON 응답 예시
잘못된 요청 (400)	{"error":"이름은 필수 항목입니다"}
찾을 수 없음 (404)	{"error":"해당 사용자가 존재하지 않습니다"}
서버 오류 (500)	{"error":"서버 내부 오류가 발생했습니다"}

if (!isset($input["name"])) {
  http_response_code(400);
  echo json_encode(["error" => "이름은 필수 항목입니다"]);
  exit;
}

에러 응답도 JSON 통일, 상태 코드 분리, 사람이 읽기 쉬운 메시지 세 가지를 지켜주는 게 좋습니다.

 

Q $_POST 대신 php://input을 써야 하는 이유가 뭐예요?

클라이언트가 JSON으로 데이터를 보낼 경우 $_POST에는 아무 값도 들어오지 않아요. JSON은 일반 폼데이터와 다르게 전송되기 때문에 php://input으로 본문을 직접 읽어야 합니다.

A JSON 요청은 $_POST로 안 들어오니 반드시 php://input으로 받아야 해요!

Q json_encode() 쓸 때 한글이 깨져요. 해결 방법은?

JSON_UNESCAPED_UNICODE 옵션을 추가하면 됩니다. 기본 옵션에선 유니코드로 변환되기 때문에 깨지거나 \uXXXX 형태로 표시돼요.

A json_encode($data, JSON_UNESCAPED_UNICODE)로 한글 깨짐 방지하세요!

Q 배열을 json_encode() 하면 순서가 유지되나요?

PHP 배열이 인덱스 배열이면 순서가 유지됩니다. 단, 연관 배열이나 객체는 순서가 보장되지 않으므로 주의가 필요해요. 순서를 중요하게 다루려면 숫자 인덱스를 사용하는 게 좋아요.

A 인덱스 배열이면 순서 유지 OK! 객체는 순서 보장되지 않아요.

Q JSON 요청을 받을 때 보안적으로 주의할 점은?

json_decode() 후 is_array()로 타입 확인을 하고, 필요한 필드가 있는지 isset() 또는 ??로 점검해야 합니다. 무조건 신뢰하면 안 돼요!

A JSON도 외부 입력이므로 꼭 유효성 검사 필수입니다!

Q REST API 응답은 항상 JSON이어야 하나요?

대부분의 경우 JSON을 사용하지만, 이미지, 파일 다운로드 등은 다른 MIME 타입이 필요할 수 있습니다. 하지만 기본 데이터 응답은 JSON을 표준으로 사용하는 것이 좋습니다.

A 기본 데이터는 JSON으로, 파일 전송은 상황에 맞게 타입 변경하세요!

 

저는 처음 JSON을 다룰 때 뭔가 복잡하고 어렵게만 느껴졌어요. 그런데 직접 json_encode()와 json_decode()를 써보면서 데이터를 주고받고, 간단한 API를 만들어보니 확실히 감이 오더라고요. 중요한 건, 작동하는 코드를 한 줄이라도 직접 써보는 거예요. 이번 글에서 소개한 JSON 처리법과 REST API 구조는 실제로 제가 실무에서 매일 쓰고 있는 방법이에요. 천천히 따라 해보면 어느새 자신도 모르게 백엔드 개발자다운 감각이 생길 거예요. 잘 모를 땐, 일단 echo부터 찍어보세요 😉