목차
REST API란 무엇인가
사용자 조회와 게시글 저장 같은 요청을 서버에 전달할 때 REST API는 리소스 주소와 HTTP 메서드로 작업을 구분합니다. REST API는 웹의 HTTP 규칙을 활용해 클라이언트와 서버가 리소스(사용자, 게시글, 상품처럼 관리할 대상)를 주고받는 설계 방식입니다.
REST API를 이해할 때는 특정 함수 이름보다 “어떤 리소스를 어떤 HTTP 메서드로 다루는가”를 먼저 봐야 합니다. 같은 주소라도 메서드에 따라 조회, 생성, 수정, 삭제의 의미가 달라질 수 있습니다.
리소스 중심 URI 설계
URI는 동작보다 리소스를 나타내는 명사 중심으로 설계합니다. 예를 들어 게시글 목록은 /posts, 특정 게시글은 /posts/42처럼 표현하며, /getPosts나 /deletePost처럼 동사를 주소에 넣는 방식은 피하는 편이 일관적입니다.
하위 리소스는 관계가 분명할 때만 연결합니다. 특정 사용자의 게시글을 의미한다면 /users/7/posts처럼 표현할 수 있지만, 경로가 지나치게 길어지면 /posts?userId=7 같은 쿼리 파라미터가 더 읽기 쉬울 수 있습니다.
HTTP 메서드와 상태 코드
GET은 조회, POST는 대상 리소스가 정한 처리(흔히 새 리소스 생성), PUT은 지정한 리소스의 생성 또는 표현 교체, PATCH는 일부 수정, DELETE는 삭제 요청에 사용합니다. 예를 들어 게시글을 조회할 때는 GET /posts/42, 새 게시글을 만들 때는 POST /posts처럼 요청합니다.
응답의 상태 코드는 처리 결과를 알려줍니다. 성공적인 조회는 200 OK, 생성 완료는 201 Created, 요청 형식 오류는 400 Bad Request, 인증이 필요한 경우는 401 Unauthorized, 접근이 거부되면 403 Forbidden, 대상을 찾지 못하면 404 Not Found를 사용할 수 있습니다. HTTP 표준 RFC 9110에 따르면 401 응답은 적용할 인증 방식을 담은 WWW-Authenticate 챌린지를 포함해야 합니다. 403은 요청을 이해했지만 처리를 거부했다는 뜻이며, 404는 존재를 숨기기 위해 사용될 수도 있어 상태 코드만으로 원인을 확정하지 않습니다. 응답 헤더와 API 문서를 함께 확인하세요.
202 Accepted는 요청을 받아들였다는 뜻이지 처리가 이미 완료됐다는 뜻은 아닙니다. 비동기 작업이라면 API가 안내하는 상태 조회 방법이나 완료 알림을 확인하세요. 204 No Content는 성공 응답에 본문이 없는 경우이므로 무조건 JSON 본문을 파싱하지 않아야 합니다. 자세한 의미는 HTTP 표준을 확인하세요.
JSON 표현과 직렬화
서버 내부의 객체나 데이터베이스 행을 HTTP 응답으로 전달할 때 JSON 표현으로 직렬화할 수 있습니다. 클라이언트가 받은 JSON을 프로그램 객체로 바꾸는 과정은 역직렬화입니다. REST가 JSON을 필수로 요구하는 것은 아니며, 지원하는 표현 형식은 API 문서와 응답의 Content-Type 헤더에서 확인해야 합니다.
예를 들어 게시글 응답은 다음처럼 구성할 수 있습니다.
{
"id": 42,
"title": "REST API 이해하기",
"published": true
}
필드 이름과 자료형을 일관되게 정하면 클라이언트 개발이 쉬워집니다. 날짜 형식, 누락된 값, 오류 응답 구조도 초기에 규칙을 정해 두면 API를 사용하는 쪽의 예외 처리가 줄어듭니다.
무상태성과 멱등성
REST의 무상태성은 서버가 이전 요청의 상태에 의존하지 않고, 각 요청이 처리에 필요한 정보를 스스로 포함해야 한다는 제약입니다. 인증 토큰과 대상 URI를 요청마다 보내면 서버를 여러 대로 확장하기 쉬워지지만, 로그인 상태 같은 정보를 서버 메모리에만 저장하면 요청이 다른 서버로 전달될 때 문제가 생길 수 있습니다.
멱등성은 같은 요청을 여러 번 보내도 서버에 의도한 효과가 한 번 보낸 것과 같은 성질입니다. 응답 코드가 매번 같거나 로그가 한 번만 기록된다는 뜻은 아닙니다. 예를 들어 삭제 요청은 처음에 성공하고 다음에는 404를 반환할 수 있습니다. 상세 의미는 HTTP 표준 RFC 9110을 참고하세요. GET, PUT, DELETE는 일반적으로 멱등적으로 설계하고, POST는 호출할 때마다 새 리소스가 생길 수 있어 보통 멱등적이지 않습니다. 네트워크 오류 뒤 요청을 재시도해야 한다면 POST에 중복 방지용 요청 키를 적용할지 별도로 정해야 합니다.
예를 들어 PUT 요청이 성공했는데 응답만 유실되면 같은 요청을 다시 보내도 게시글의 최종 내용은 같아야 합니다. 반면 POST를 무조건 재전송하면 주문이나 결제가 중복 생성될 수 있으므로, 서버 로그와 생성 결과를 확인하거나 중복 요청 처리 정책을 마련해야 합니다.
HTTP 요청 결과 확인 순서
- 요청: 대상 URI와 메서드 확인
- 응답: 상태 코드와 인증 헤더 확인
- 표현: Content-Type과 본문 확인
- 재시도: 멱등성과 중복 처리 확인
결론
REST API 이해하기의 핵심은 리소스 중심 URI, 메서드와 상태 코드의 조합, JSON 변환, 무상태성, 멱등성입니다. 이 다섯 가지를 기준으로 보면 API 문서와 설계 의도를 훨씬 빠르게 파악할 수 있습니다.