REST API 요청과 응답 구조 이해하기

REST API는 어떻게 동작할까요?

REST API는 웹이나 앱 같은 클라이언트가 서버의 데이터를 조회하거나 변경할 때 사용하는 인터페이스입니다. 가장 기본적인 흐름은 단순합니다. 클라이언트가 특정 주소로 요청을 보내면, 서버는 요청 내용을 확인한 뒤 결과를 응답으로 반환합니다.

예를 들어 쇼핑몰 앱에서 상품 목록을 열면 앱은 서버에 상품 데이터를 요청합니다. 서버는 데이터베이스에서 상품 정보를 찾고, 보통 JSON 형식으로 결과를 보냅니다. 이때 요청과 응답은 HTTP라는 웹 통신 규칙을 따릅니다. REST API의 기초를 익힐 때는 ‘무엇을 요청하는가’, ‘어디로 요청하는가’, ‘서버가 어떤 결과를 돌려주는가’를 나누어 이해하는 학습방법이 효과적입니다.

요청 구조: 메서드, URL, 헤더, 본문

API 요청은 일반적으로 HTTP 메서드, URL, 헤더(Header), 본문(Body)으로 구성됩니다.

첫째, HTTP 메서드는 요청의 목적을 나타냅니다. GET은 데이터를 조회할 때 사용합니다. POST는 새 데이터를 만들 때 사용합니다. PUT 또는 PATCH는 기존 데이터를 수정할 때 사용하며, DELETE는 데이터를 삭제할 때 사용합니다. 실제 서비스의 설계에 따라 세부 규칙은 달라질 수 있지만, 이 역할을 먼저 기억하면 API 문서를 읽기 쉬워집니다.

둘째, URL은 요청 대상의 위치입니다. 예를 들어 GET /users/42는 42번 사용자를 조회한다는 의미로 설계할 수 있습니다. 여기서 /users는 사용자라는 자원(resource)을, 42는 특정 자원의 식별자를 뜻합니다. /products?category=book처럼 물음표 뒤에 조건을 붙이는 쿼리 파라미터도 자주 사용됩니다.

셋째, 헤더는 요청에 대한 부가 정보입니다. JSON 데이터를 보낼 때는 Content-Type: application/json을 설정합니다. 로그인이 필요한 API에서는 Authorization 헤더에 토큰을 담는 경우가 많습니다.

넷째, 본문은 서버로 전달할 실제 데이터입니다. 주로 POST, PUT, PATCH 요청에서 사용합니다. 예를 들어 사용자 생성 요청의 본문은 {"name":"민지","email":"[email protected]"}처럼 작성할 수 있습니다.

응답 구조: 상태 코드와 JSON 데이터

서버의 응답도 상태 코드, 헤더, 본문으로 이루어집니다. 이 중 초보자가 가장 먼저 확인할 부분은 상태 코드입니다.

200 OK는 요청이 정상적으로 처리되었음을 뜻합니다. 201 Created는 새 자원이 성공적으로 생성되었을 때 주로 사용합니다. 400 Bad Request는 요청 형식이나 값이 잘못된 경우, 401 Unauthorized는 인증 정보가 없거나 유효하지 않은 경우에 반환될 수 있습니다. 404 Not Found는 요청한 주소나 데이터를 찾지 못했다는 의미이며, 500 Internal Server Error는 서버 내부 처리 중 문제가 발생했음을 나타냅니다.

응답 본문에는 처리 결과가 JSON으로 담기는 경우가 많습니다. 예를 들어 사용자 조회 성공 응답은 {"id":42,"name":"민지","email":"[email protected]"}와 같은 형태가 될 수 있습니다. 오류 응답에는 {"message":"User not found"}처럼 원인을 설명하는 메시지가 포함되기도 합니다. 상태 코드와 응답 본문을 함께 확인해야 문제의 원리를 정확히 파악할 수 있습니다.

Python으로 요청과 응답 확인하기

Python에서는 requests 라이브러리를 사용하면 API 통신을 간단히 연습할 수 있습니다. 다음 코드는 공개 테스트 API에 GET 요청을 보내고 응답을 확인하는 예입니다.

import requests

response = requests.get('https://jsonplaceholder.typicode.com/posts/1')
print(response.status_code)
print(response.json())

status_code로 HTTP 상태 코드를 확인하고, json()으로 JSON 응답을 파이썬 딕셔너리 형태로 변환할 수 있습니다. POST 요청은 json 매개변수에 보낼 데이터를 넣어 작성합니다.

payload = {'title': 'API 연습', 'body': '요청 본문입니다', 'userId': 1}
response = requests.post('https://jsonplaceholder.typicode.com/posts', json=payload)
print(response.status_code)
print(response.json())

실제 서버 API를 호출할 때는 API 문서에서 URL, 지원 메서드, 필요한 헤더, 요청 본문 형식, 예상 응답을 먼저 확인하세요. 특히 인증 토큰과 개인정보는 코드나 화면 캡처에 노출하지 않도록 주의해야 합니다.

처음 API를 학습하는 방법

API 학습은 작은 요청 하나를 직접 관찰하는 것부터 시작하는 것이 좋습니다. 먼저 GET 요청으로 데이터를 조회하고, URL과 응답 JSON의 각 필드를 읽어 보세요. 다음으로 쿼리 파라미터를 바꾸어 결과가 어떻게 달라지는지 확인합니다. 이후 POST 요청으로 본문을 전송하고 200, 201, 400 같은 상태 코드가 어떤 상황에서 나타나는지 비교해 보세요.

오류가 발생하면 URL 철자, HTTP 메서드, Content-Type 헤더, JSON 필드 이름과 자료형을 순서대로 점검하면 됩니다. 브라우저 개발자 도구의 Network 탭, Postman 같은 API 테스트 도구, Python 코드 중 하나를 선택해 요청과 응답을 반복해서 확인해 보세요. REST API의 핵심은 복잡한 문법보다도 요청의 의도와 응답의 의미를 정확히 읽는 데 있습니다.

자주 묻는 질문