목차
REST API란 무엇인가
이 글은 HTTP와 JSON의 기본 개념을 알고 있으며, 서버에 데이터를 요청하거나 저장하는 상황을 전제로 합니다. 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를 사용합니다. 클라이언트는 응답 본문만 보지 말고 상태 코드도 함께 확인해야 합니다.
JSON 표현과 직렬화
서버 내부의 객체나 데이터베이스 행은 그대로 전송하지 않고 JSON이라는 표현 형식으로 변환합니다. 이 변환 과정을 직렬화라고 하며, 클라이언트가 받은 JSON을 프로그램 객체로 바꾸는 과정은 역직렬화입니다.
예를 들어 게시글 응답은 다음처럼 구성할 수 있습니다.
{
"id": 42,
"title": "REST API 이해하기",
"published": true
}
필드 이름과 자료형을 일관되게 정하면 클라이언트 개발이 쉬워집니다. 날짜 형식, 누락된 값, 오류 응답 구조도 초기에 규칙을 정해 두면 API를 사용하는 쪽의 예외 처리가 줄어듭니다.
무상태성과 멱등성
REST의 무상태성은 서버가 이전 요청의 상태에 의존하지 않고, 각 요청이 처리에 필요한 정보를 스스로 포함해야 한다는 제약입니다. 인증 토큰과 대상 URI를 요청마다 보내면 서버를 여러 대로 확장하기 쉬워지지만, 로그인 상태 같은 정보를 서버 메모리에만 저장하면 요청이 다른 서버로 전달될 때 문제가 생길 수 있습니다.
멱등성은 같은 요청을 여러 번 보내도 최종 결과가 한 번 보낸 것과 같아지는 성질입니다. GET, PUT, DELETE는 일반적으로 멱등적으로 설계하고, POST는 호출할 때마다 새 리소스가 생길 수 있어 보통 멱등적이지 않습니다. 네트워크 오류 뒤 요청을 재시도해야 한다면 POST에 중복 방지용 요청 키를 적용할지 별도로 정해야 합니다.
예를 들어 PUT 요청이 성공했는데 응답만 유실되면 같은 요청을 다시 보내도 게시글의 최종 내용은 같아야 합니다. 반면 POST를 무조건 재전송하면 주문이나 결제가 중복 생성될 수 있으므로, 서버 로그와 생성 결과를 확인하거나 중복 요청 처리 정책을 마련해야 합니다.
결론
REST API 이해하기의 핵심은 리소스 중심 URI, 메서드와 상태 코드의 조합, JSON 변환, 무상태성, 멱등성입니다. 이 다섯 가지를 기준으로 보면 API 문서와 설계 의도를 훨씬 빠르게 파악할 수 있습니다.