REST API란 무엇인가요?
REST API(Representational State Transfer 애플리케이션 프로그래밍 인터페이스)는 웹을 구동하는 네트워크 애플리케이션을 설계하고 빌드하는 표준으로 널리 알려진 아키텍처 스타일입니다. REST API는 따를 경우 단순하고 확장 가능하며 통합하기 쉬운 웹 서비스를 만들 수 있는 일련의 규칙과 제약 조건을 제공합니다.
REST API 정의
REST API는 REST 아키텍처 스타일의 설계 원칙을 준수하는 API입니다. REST는 기본적으로 리소스라는 개념을 중심으로 이루어지며, 리소스는 사용자, 제품, 문서, 항목 모음과 같은 모든 정보 조각이 될 수 있습니다.
REST API는 클라이언트 애플리케이션이 사전 정의된 스테이트리스(stateless) 작업 집합을 사용하여 이러한 리소스에 액세스하고 조작할 수 있는 방법을 제공합니다.
REST API는 어떻게 작동하나요?
1. 클라이언트가 요청을 보냄
클라이언트 애플리케이션(예: 모바일 앱, 웹브라우저 또는 다른 서버)이 API에 작업을 수행하도록 요청을 시작합니다. 이 요청은 특정 URL로 전송되며 HTTP 메서드, 메타데이터가 포함된 헤더, 때로는 데이터가 포함된 요청 본문을 포함합니다.
2. 서버가 요청을 처리함
서버는 요청을 수신하고 검증하여 클라이언트가 인증되었으며 요청된 작업을 수행할 권한이 있는지 확인합니다. 그런 다음 데이터베이스에서 데이터를 검색하거나, 새 리소스를 만들거나, 기존 리소스를 업데이트하는 등의 요청을 처리합니다.
3. 서버가 응답을 보냄
요청을 처리한 후 서버는 클라이언트에 응답을 다시 보냅니다. 이 응답에는 결과(예: 성공 시 200 OK, 리소스가 존재하지 않는 경우 404 찾을 수 없음, 보안 문제 시 401 승인되지 않음)를 나타내는 HTTP 상태 코드와 함께 요청된 데이터가 응답 본문에 포함됩니다.
4. 데이터 전송
클라이언트와 서버 간에 전송되는 데이터는 리소스 상태의 '표현'입니다. JSON(JavaScript Object Notation)은 경량화되어 있고 사람이 읽을 수 있으며 프로그래밍 언어로 쉽게 파싱할 수 있기 때문에 이러한 데이터에 가장 널리 사용되는 형식입니다.
REST API 아키텍처 및 구성요소
REST의 강력한 성능과 확장성은 설계를 안내하는 일련의 아키텍처 제약 조건에서 비롯됩니다. 이러한 제약 조건을 준수하는 시스템을 'RESTful'이라고 합니다.
리소스
리소스는 REST의 기본 개념입니다. 유형, 연결된 데이터, 다른 리소스와의 관계, 리소스에서 작동하는 메서드 집합이 있는 객체입니다. 예를 들어 전자상거래 API에서 '제품' 또는 '고객'은 리소스가 됩니다.
URI(Uniform Resource Identifier)
각 리소스는 URI로 고유하게 식별됩니다. 잘 설계된 API는 깔끔하고 설명적이며 일관된 URI를 사용하여 리소스를 식별합니다. 예를 들어 /users는 사용자 모음을 식별하고 /users/123은 ID가 123인 특정 사용자를 식별합니다.
표현
클라이언트는 리소스와 직접 상호작용하는 것이 아니라 리소스의 표현과 상호작용합니다. 가장 일반적인 표현 형식은 JSON이지만 XML이나 HTML과 같은 다른 형식도 사용할 수 있습니다. 이를 통해 리소스의 상태를 유연하게 표현할 수 있습니다.
스테이트리스(Stateless)
클라이언트에서 서버로 보내는 모든 요청에는 서버가 요청을 이해하고 처리하는 데 필요한 모든 정보가 포함되어야 합니다. 서버는 요청 간에 클라이언트 컨텍스트나 세션 상태를 저장하지 않습니다. 이 제약 조건으로 인해 모든 서버가 모든 요청을 처리할 수 있으므로 REST API는 확장성이 뛰어납니다.
클라이언트-서버 아키텍처
클라이언트와 서버는 분리되어 있으며 API가 둘 사이의 인터페이스 역할을 합니다. 작업 분리를 통해 클라이언트 측 애플리케이션과 서버 측 애플리케이션을 독립적으로 발전시킬 수 있습니다.
일관된 인터페이스
REST에는 클라이언트와 서버 간에 일관되고 균일한 인터페이스가 필요합니다. 이는 표준 HTTP 메서드, 리소스 식별을 위한 URI, Hypermedia as the Engine of Application State(HATEOS)를 사용하여 달성됩니다.
캐시 저장 가능성
서버의 응답은 캐시 가능 또는 캐시 불가능으로 정의되어야 합니다. 응답을 캐시할 수 있는 경우 클라이언트 또는 중개자가 후속 동일 요청에 대해 해당 응답을 재사용할 수 있으므로 성능이 크게 향상되고 서버 부하가 줄어듭니다.
계층화된 시스템
REST API에 연결된 클라이언트는 일반적으로 최종 서버에 직접 연결되어 있는지 아니면 중간에 있는 중개자에 연결되어 있는지 알 수 없습니다. API 게이트웨이 또는 부하 분산기와 같은 중개 서버를 아키텍처에 도입하여 확장성, 보안, 성능을 개선할 수 있습니다.
REST API 권장사항
리소스에 명사 사용
URI는 리소스를 나타내야 하므로 동사가 아닌 명사(컬렉션의 경우 복수, 특정 항목의 경우 단수 또는 ID)를 사용해야 합니다. 예를 들어 /getAllUsers가 아닌 /users를 사용하여 모든 사용자를 나타냅니다.
HTTP 메서드 올바르게 사용
표준 HTTP 동사를 사용하여 작업을 나타냅니다. 검색에는 GET, 생성에는 POST, 업데이트에는 PUT, 삭제에는 DELETE를 사용합니다. 이를 통해 예측 가능하고 일관된 인터페이스를 만들 수 있습니다.
HATEOAS(Hypermedia as the Engine of Application State) 구현
REST의 핵심 원칙은 응답에 다른 관련 작업 또는 리소스에 대한 링크가 포함되어야 한다는 것입니다. 이를 통해 클라이언트는 URI 패턴을 하드 코딩하지 않고도 API를 동적으로 탐색할 수 있습니다.
버전 관리
API에 브레이킹 체인지를 적용해야 하는 경우 새 버전을 도입합니다. 가장 일반적인 방법은 /api/v2/users와 같이 URI에 버전 번호를 포함하는 것입니다. 기존 클라이언트는 이전 버전을 계속 사용할 수 있으며 신규 클라이언트는 새 버전을 도입할 수 있습니다.
오류를 정상적으로 처리
요청이 실패하면 응답 본문에 적절한 HTTP 상태 코드(예: 400 잘못된 요청, 500 내부 서버 오류)와 함께 명확하고 유용한 오류 메시지를 제공합니다. 이를 통해 클라이언트 측 개발자는 무엇이 잘못되었는지 파악할 수 있습니다.
보안(인증 및 승인)
클라이언트의 ID와 승인을 확인하기 위해 강력한 인증(예: OAuth 2.0, API 키)을 구현하여 API를 보호합니다. 이렇게 하면 클라이언트가 허용된 리소스에만 액세스할 수 있습니다. 항상 TLS/SSL을 사용하여 트래픽을 암호화합니다.
페이지 나누기, 필터링, 정렬
많은 수의 항목을 반환할 수 있는 엔드포인트의 경우 페이지 나누기를 구현하여 데이터를 관리 가능한 청크로 반환합니다. 또한 클라이언트가 결과를 필터링하고 정렬할 수 있도록 쿼리 파라미터를 제공하여 전송되는 데이터의 양을 줄입니다.
REST API 사용의 이점
단순성 및 가독성
단순성 및 가독성
REST API는 표준 HTTP 메서드와 사람이 읽을 수 있는 URI를 사용하므로 개발자가 비교적 쉽게 배우고, 사용하고, 디버깅할 수 있습니다. 인터페이스의 자기 서술적 특성 덕분에 통합 작업이 간소화됩니다.
확장성
확장성
REST의 스테이트리스(stateless) 특성은 확장성을 가능하게 하는 핵심 요소입니다. 서버가 클라이언트 세션을 유지할 필요가 없으므로 여러 서버에 요청을 쉽게 분산할 수 있으며, 복잡성 없이 증가된 부하를 처리하기 위해 새 서버를 추가할 수 있습니다.
유연성
유연성
REST는 다양한 데이터 형식을 지원하며, JSON은 경량화되어 있고 널리 지원되기 때문에 가장 많이 사용되는 형식입니다. 이러한 유연성 덕분에 REST API는 웹브라우저부터 모바일 기기, IoT 센서에 이르기까지 광범위한 클라이언트 애플리케이션에서 사용할 수 있습니다.
클라이언트와 서버의 분리
클라이언트와 서버의 분리
REST에서 적용하는 클라이언트-서버 아키텍처는 작업을 명확하게 분리합니다. 이를 통해 개발자는 클라이언트 측 프런트엔드와 서버 측 백엔드에서 독립적으로 작업할 수 있으므로 개발 주기를 단축할 수 있습니다.
언어 제약 없음
언어 제약 없음
REST는 표준 HTTP를 기반으로 빌드된 아키텍처 스타일이므로 모든 프로그래밍 언어로 구현할 수 있으며 HTTP 요청을 수행할 수 있는 모든 클라이언트에서 사용할 수 있습니다. 이를 통해 다양한 기술 스택 간에 최대한의 상호 운용성을 제공합니다.
REST API 예시
공개 API 예시
일반적인 사용 사례는 모바일 날씨 앱이 공개 날씨 API에서 특정 위치의 현재 날씨를 가져오는 것입니다.
클라이언트 애플리케이션은 위치와 인증을 위한 API 키를 포함하여 API 엔드포인트에 HTTP GET 요청을 보냅니다.
curl "https://api.weather-service.com/v1/current?location=94043&key=YOUR_API_KEY" |
curl
"https://api.weather-service.com/v1/current?location=94043&key=YOUR_API_KEY"
서버는 요청을 처리하고 지정된 위치의 날씨 데이터를 검색하여 JSON 응답을 반환합니다.
{ "temperature": 20, "unit": "celsius", "condition": "Clear", "humidity": 55 } |
{
"temperature": 20,
"unit": "celsius",
"condition": "Clear",
"humidity": 55
}
내부 API 예시
마이크로서비스 아키텍처에서는 '제품' 서비스가 전자상거래 사이트에 가격을 표시하기 전에 '인벤토리' 서비스에서 업데이트된 가격을 가져와야 할 수 있습니다.
제품 서비스는 특정 제품 ID에 대해 인벤토리 서비스의 API 엔드포인트에 내부 HTTP GET 요청을 보냅니다.
curl "http://inventory-service.internal/api/products/PN-5821/price" |
curl
"http://inventory-service.internal/api/products/PN-5821/price"
인벤토리 서비스는 현재 가격을 조회하고 간단한 JSON 응답을 반환합니다.
{ "productId": "PN-5821", "price": 1299.99, "currency": "USD" } ``` |
{
"productId": "PN-5821",
"price": 1299.99,
"currency": "USD"
}
```
추가 리소스
- Google API 탐색기는 브라우저에서 바로 다양한 Google REST API를 탐색하고 테스트할 수 있는 대화형 도구입니다.
- 이 블로그 게시물은 RESTful 웹 API를 설계하고 개발하기 위한 권장사항에 대한 종합 가이드를 제공합니다.
- Google Cloud Skills Boost의 Cloud Hero 학습 과정은 API 관리에 대한 실무 경험을 쌓을 수 있는 실무형 실습을 제공합니다.
