RESTful API
IT 위키
RESTful API(Representational State Transfer Application Programming Interface)는 REST 아키텍처 스타일을 따르는 웹 API로, 클라이언트와 서버 간의 통신을 간단하고 일관된 방식으로 설계한 인터페이스이다.
개요[편집 | 원본 편집]
RESTful API는 HTTP 프로토콜을 기반으로 자원을 URI(Uniform Resource Identifier)로 표현하고, HTTP 메서드(GET, POST, PUT, DELETE 등)를 통해 자원을 조작한다. REST 아키텍처는 상태 비저장(stateless), 클라이언트-서버 구조, 캐시 처리, 계층 구조 등의 제약 조건을 따르며, 이를 만족하는 API는 RESTful하다고 간주된다.
구성 요소[편집 | 원본 편집]
RESTful API는 다음과 같은 구성 요소를 기반으로 설계된다.
- 자원(Resource): 고유한 URI로 식별되며, 명사 형태로 표현됨 (예: `/users`, `/products`)
- 메서드(Method): HTTP 메서드를 사용하여 자원에 대한 동작을 정의
- GET: 자원의 조회
- POST: 자원의 생성
- PUT: 자원의 전체 수정
- PATCH: 자원의 부분 수정
- DELETE: 자원의 삭제
- 표현(Representation): 클라이언트와 서버는 일반적으로 JSON, XML 등의 형식으로 자원의 상태를 주고받음
- 상태 비저장성: 각 요청은 독립적으로 처리되며, 서버는 이전 요청 상태를 기억하지 않음
RESTful의 설계 원칙[편집 | 원본 편집]
RESTful API를 설계할 때는 다음과 같은 원칙을 지켜야 한다.
- 일관된 URI 설계: 자원 중심의 URI를 사용하며 동사 대신 명사를 사용
- 표준 HTTP 메서드 사용: 기능에 따라 적절한 메서드를 활용
- 상태 비저장성 유지: 서버는 클라이언트의 상태를 저장하지 않음
- 계층화된 시스템: 중간 서버를 통한 로드 밸런싱, 캐싱 등이 가능
- 캐시 처리: 응답에 캐시 가능 여부를 명시하여 성능 최적화
- 자체 표현(Self-descriptive) 메시지: 요청에 필요한 모든 정보가 포함됨
URI 설계 규칙[편집 | 원본 편집]
RESTful API에서 URI는 자원을 식별하기 위한 핵심 요소로, 명확하고 일관된 규칙을 따라야 한다. 다음은 대표적인 URI 설계 규칙이다.
- URI는 명사를 사용하여 자원을 표현해야 하며, 동사는 사용하지 않는다.
- 예: `/getUserInfo` 대신 `/users/info`
- URI는 복수형 명사를 사용한다.
- 예: `/user` 보다는 `/users`
- 계층 구조를 나타내는 경우 URI 경로를 계층적으로 표현한다.
- 예: `/users/42/orders/3` (사용자 42번의 주문 3번)
- 자원의 식별자는 URI 경로에 포함시키며, 쿼리 파라미터로 넘기지 않는다.
- 예: `/users?id=42` 대신 `/users/42`
- 하위 자원(Sub-resource)은 부모 자원에 종속된 경로로 표현한다.
- 예: `/users/42/posts` (사용자 42번이 작성한 게시물)
- 파일 확장자는 URI에 포함하지 않는다. 대신 Accept 헤더를 사용해 표현 형식을 지정한다.
- 예: `/users.json` 대신 `/users` + `Accept: application/json`
- 하이픈(`-`)을 단어 구분자로 사용하고, 밑줄(`_`)은 사용하지 않는다.
- 예: `/user-profile` (권장) vs `/user_profile` (비권장)
- 소문자를 사용한다. 대문자는 피한다.
- API 버전은 URI에 명시할 수 있으나, 가능한 한 헤더 방식 버전 관리가 권장된다.
- URI 방식 예: `/v1/users`
- 헤더 방식 예: `Accept: application/vnd.example.v1+json`
장점과 단점[편집 | 원본 편집]
장점[편집 | 원본 편집]
- 단순하고 직관적인 URI 구조
- HTTP 표준을 그대로 활용하므로 다양한 플랫폼에서 호환 가능
- 클라이언트와 서버의 역할 분리
- 확장성 및 유연성 뛰어남
단점[편집 | 원본 편집]
- 복잡한 트랜잭션 처리에는 적합하지 않음
- 상태 비저장성으로 인해 반복적인 인증 정보 전송 필요
- 메시지 오버헤드가 클 수 있음(JSON 등 데이터 포맷 사용)
REST와 RESTful의 차이[편집 | 원본 편집]
REST는 아키텍처 스타일 자체를 의미하며, RESTful은 이 스타일을 구현한 API를 의미한다. 즉, 모든 RESTful API는 REST의 제약 조건을 따르지만, 실질적으로 이를 완전히 준수하지 않는 경우도 많아 "REST-like" 또는 "준REST"라는 표현이 사용되기도 한다.
활용 사례[편집 | 원본 편집]
- 클라우드 서비스(API Gateway, AWS, GCP 등)
- 모바일 애플리케이션과 서버 간 통신
- 프론트엔드와 백엔드 간 데이터 교환
- IoT 기기 제어 및 데이터 수집
같이 보기[편집 | 원본 편집]
참고 문헌[편집 | 원본 편집]
- Roy T. Fielding, *Architectural Styles and the Design of Network-based Software Architectures*, University of California, Irvine, 2000.
- Leonard Richardson, Sam Ruby, *RESTful Web Services*, O'Reilly Media, 2007.
