[Open API] #2. API 구성요소 및 API 종류

API는 소프트웨어 애플리케이션을 구축하기 위한 일련의 프로토콜과 도구입니다. API는 계약서처럼 서로 다른 소프트웨어 구성 요소가 상호 작용하는 방식을 정의합니다.

API는 서로 다른 시스템을 연결하고 서로 통신할 수 있게 해주는 다리와 같은 역할을 합니다. 서버에서 데이터를 가져오든, 원격 장치로 명령을 보내든, 타사 서비스를 애플리케이션에 통합하든, API는 이 모든 것을 가능하게 합니다.

API는 다양한 요구사항과 플랫폼에 맞춰 다양한 형태로 제공됩니다. 일부는 웹 서비스(웹 API)용으로, 일부는 운영 체제(OS API)용으로, 일부는 데이터베이스나 하드웨어용으로 설계되었습니다. API의 다양성과 편재성으로 인해 API는 현대 소프트웨어 개발에서 없어서는 안 될 필수 요소입니다.

 

---

API 구성요소

API 클라이언트
- 정의: API 클라이언트는 API 서버에 요청을 보내는 애플리케이션 또는 시스템입니다. 모바일 앱에서 브라우저 또는 다른 서버에 이르기까지 무엇이든 될 수 있습니다.
- 기능: 클라이언트는 요청을 전송하여 상호 작용을 시작하고 API 서버로부터 응답을 받습니다. API 데이터를 처리하기 위한 사용자 인터페이스와 로직을 처리합니다.

API 요청
- 역할: API 클라이언트가 작업을 수행하기 위해 요청합니다. 여기에는 서버가 이를 이해하고 처리하는 데 필요한 모든 정보가 포함됩니다.
- 구성 요소: 요청 방법(GET, POST 등), 엔드포인트 URL, 헤더(메타데이터 및 인증용), 때로는 본문(처리할 데이터용)이 포함됩니다.

API 서버
- 목적: 서버는 API를 호스팅하고 들어오는 요청을 처리합니다. 비즈니스 로직을 실행하고 데이터베이스 또는 기타 서비스와 상호 작용하며 응답을 다시 보냅니다.
- 책임: 서버는 요청 유효성 검사, 인증 및 요청된 작업의 실행을 처리합니다.

API 응답
- 정의 : 응답은 API 서버가 요청을 처리한 후 클라이언트에 다시 보내는 것입니다.
- 내용 : 일반적으로 상태 코드(성공 또는 실패를 나타냄), 응답 헤더, 요청된 데이터 또는 작업 확인을 포함하는 본문이 포함됩니다.

API 아키텍처 비교
- 구성 요소와 그 기능을 이해하는 것은 REST, SOAP, GraphQL과 같은 다양한 API 아키텍처를 비교하는 데 필수적입니다. 각 아키텍처는 이러한 구성 요소가 상호 작용하고 애플리케이션의 요구 사항을 충족하는 방식을 결정합니다.

이 블로그의 이 섹션은 독자들에게 API의 기본 요소와 API 아키텍처의 광범위한 맥락에서 각 요소의 역할에 대한 포괄적인 이해를 제공합니다. 이러한 지식은 소프트웨어 프로젝트에서 API를 효과적으로 설계, 사용 또는 통합하기 위한 토대를 형성합니다.

 

---

API 아키텍처

소프트웨어 개발 영역에서는 다양한 API 아키텍처가 각기 다른 용도로 사용됩니다. 가장 눈에 띄는 세 가지 유형은 REST, SOAP, GraphQL입니다. 각각 고유한 특성을 가지고 있으며 다양한 시나리오에 적합합니다.

REST
- 설계 철학: REST는 기존 HTTP 프로토콜을 사용하는 아키텍처 스타일입니다. 단순성과 상태 비저장성으로 잘 알려져 있습니다.
- 장점: REST는 이해하고 구현하기 쉽습니다. 다양한 데이터 형식을 지원하며 확장성이 뛰어나 특히 고성능과 확장성이 필요한 웹 서비스에 이상적입니다.
- 단점: REST는 전체 데이터 집합을 조합하는 데 여러 요청이 필요할 수 있으므로 복잡한 쿼리 작업에는 효율성이 떨어질 수 있습니다.

SOAP
- 설계 철학: SOAP는 구조화된 정보를 교환하기 위한 프로토콜로, 메시징에 XML을 사용합니다.
- 장점: 오류 처리 및 보안 기능(예: WS-Security)이 내장되어 있어 고도로 표준화되어 있습니다. 보안과 트랜잭션 안정성이 가장 중요한 엔터프라이즈급 애플리케이션에서 SOAP를 선호합니다.
- 단점: 장황한 XML 형식으로 인해 SOAP 메시지의 크기가 커지고 구문 분석 속도가 느려져 성능 오버헤드가 발생합니다.

GraphQL
- 설계 철학: GraphQL은 API를 위한 쿼리 언어입니다. 클라이언트가 필요한 데이터를 정확하게 요청할 수 있습니다.
- 장점: 효율적인 데이터 검색으로 데이터의 과도한 가져오기를 줄입니다. 유연하며 구독을 통해 실시간 업데이트가 가능합니다.
- 단점: 서버 측에서 구현하고 캐싱을 관리하는 것이 복잡할 수 있습니다. 데이터 스키마에 대한 충분한 이해가 필요합니다.

올바른 아키텍처 선택하기
- 요구 사항 고려하기 : 범용 웹 애플리케이션에는 REST가, 엄격한 보안과 복잡한 트랜잭션이 필요한 애플리케이션에는 SOAP가, 복잡한 데이터가 필요한 애플리케이션과 대역폭 사용량을 최소화해야 하는 모바일 애플리케이션에는 GraphQL이 적합합니다.
- 향후 트렌드: 프론트엔드 애플리케이션의 경우 GraphQL과 같은 보다 유연하고 효율적인 아키텍처로 전환하는 추세이지만, 광범위한 백엔드 서비스에는 여전히 REST가 강력한 선택지입니다.

결론적으로, 데이터의 특성, 필요한 보안 수준, 클라이언트의 요구사항, 상호 작용의 복잡성 등 프로젝트의 구체적인 요구사항에 따라 REST, SOAP, GraphQL 중 어떤 것을 선택할지 결정해야 합니다.

 

 

---

RESTful API

REST(Representational State Transfer) 아키텍처 스타일에 기반한 RESTful API는 최신 웹 서비스 개발의 초석이 되었습니다. 효율적이고 확장 가능한 웹 서비스를 만들려면 RESTful 설계의 원칙과 그 이점을 이해하는 것이 중요합니다.

RESTful 설계의 원칙:
1. 클라이언트-서버 아키텍처: 이 원칙은 사용자 인터페이스 문제와 데이터 저장 문제를 분리하여 여러 플랫폼에서 사용자 인터페이스의 이식성을 향상시킵니다.
2. 상태 비저장성: 클라이언트에서 서버로 보내는 각 요청에는 요청을 이해하고 처리하는 데 필요한 모든 정보가 포함되어야 합니다. 서버는 요청 사이에 어떠한 클라이언트 컨텍스트도 저장하지 않습니다.
3. 캐시 가능성: 응답을 캐시 가능 또는 캐시 불가능으로 정의해야 서버와 네트워크의 부하를 줄여 클라이언트 측 성능을 개선할 수 있습니다.
4. 통일된 인터페이스: 아키텍처를 단순화하고 분리하여 각 부분이 독립적으로 발전할 수 있도록 합니다. 여기에는 리소스 기반 URL, 표준화된 HTTP 메서드, 하이퍼미디어를 애플리케이션 상태 엔진(HATEOAS)으로 사용하는 것이 포함됩니다.
5. 계층화된 시스템: 클라이언트-서버 상호 작용을 중개 서버가 중개하여 확장성을 개선하고 보안 정책을 시행할 수 있습니다.
6. 주문형 코드 : 서버는 실행 코드를 전송하여 클라이언트의 기능을 일시적으로 확장하거나 사용자 지정할 수 있습니다.

RESTful API의 장점
- 확장성: 상태 비저장성 및 캐싱 지원으로 인해 RESTful API는 많은 수의 요청을 효율적으로 처리할 수 있습니다.
- 단순성 및 유연성: 표준 HTTP 메서드를 활용하기 때문에 이해하고 구현하기 쉽습니다. JSON 및 XML과 같은 여러 데이터 형식을 지원할 수 있습니다.
- 폭넓은 수용성: RESTful API는 웹의 설계 원칙을 따르기 때문에 웹 서비스 개발을 위한 자연스러운 선택입니다.
- 손쉬운 소모성: 간단한 구조로 인해 브라우저와 모바일 앱을 비롯한 다양한 클라이언트 애플리케이션에서 쉽게 소모할 수 있습니다.

RESTful API의 사용 사례:
- 웹 서비스 및 모바일 애플리케이션 : 서버와 통신하기 위해 표준 인터페이스가 필요한 애플리케이션에 이상적입니다.
- 마이크로서비스 아키텍처: 확장성과 유연성 때문에 마이크로서비스 아키텍처에서 RESTful API가 일반적으로 사용됩니다.
- 사물 인터넷(IoT): 가벼운 특성으로 인해 장치가 인터넷을 통해 통신해야 하는 IoT 애플리케이션에 적합합니다.

요약하자면, RESTful API는 인터넷의 원칙과 아키텍처를 준수하는 웹 서비스를 구축할 수 있는 효율적이고 유연하며 확장 가능한 방법을 제공합니다. 이는 최신 웹 개발자와 아키텍트의 툴킷에서 필수적인 도구입니다.

 

---

SOAP API

SOAP(Simple Object Access Protocol)는 웹 서비스 통신을 위한 프로토콜 표준으로, 주로 XML을 사용하여 메시지를 구조화합니다.

SOAP API의 구조:
1. XML 기반: SOAP 메시지는 메시지 교환을 위한 엄격하고 표준화된 구조를 정의하는 XML로 형식화됩니다.
2. 엔벨로프 구조: SOAP 메시지는 헤더(선택 사항)와 본문을 포함할 수 있는 엔벨로프로 구성됩니다. 헤더는 메시지 처리를 위한 정보를 제공하고 본문은 실제 메시지 데이터를 전달합니다.
3. WS-* 표준 지원: SOAP는 보안(WS-Security), 트랜잭션(WS-AtomicTransaction), 신뢰성 있는 메시징(WS-ReliableMessaging)과 같은 고급 기능을 위한 일련의 웹 서비스 사양(WS-*)을 구현할 수 있습니다.

SOAP API의 사용 사례:
- 엔터프라이즈급 애플리케이션: SOAP는 높은 수준의 보안과 강력한 트랜잭션 관리가 요구되는 엔터프라이즈 환경에서 자주 사용됩니다.
- 금융 서비스 : 은행과 금융 기관은 안전한 거래와 서비스를 위해 SOAP를 사용합니다.
- 의료 시스템: 의료 분야에서는 엄격한 보안 표준을 준수해야 하는 민감한 환자 데이터를 교환하는 데 SOAP가 사용됩니다.

SOAP와 REST의 차이점:
- 표준화 및 복잡성: SOAP는 REST보다 더 엄격하게 표준화되어 있으며, XML과 WS-* 표준을 광범위하게 사용하기 때문에 일반적으로 더 복잡합니다.
- 프로토콜 및 전송: REST는 일반적으로 HTTP/HTTPS를 사용하지만, SOAP는 HTTP, SMTP, TCP 등 모든 전송 프로토콜을 통해 작동할 수 있습니다.
- 보안: SOAP에는 보안 및 프로토콜 표준이 내장되어 있어 복잡한 보안 구현이 필요한 시나리오에서 선호되는 선택입니다.
- 유연성 대 형식성: REST는 더 많은 유연성을 제공하며 일반적으로 사용 및 구현이 더 쉽습니다. 반면, SOAP는 보다 형식적인 규칙 기반 접근 방식을 제공하므로 특정 비즈니스 애플리케이션에 유리할 수 있습니다.

요약하자면, SOAP의 구조화된 형식과 포괄적인 표준은 엄격한 보안과 안정적인 메시지 전달이 필요한 시나리오에 적합합니다. REST보다 번거롭다는 인식에도 불구하고 SOAP는 웹 서비스 환경, 특히 그 기능이 필수적인 특정 산업과 애플리케이션에서 여전히 중요한 부분을 차지하고 있습니다.

 

 

---

GraphQL

API를 위한 최신 데이터 쿼리 및 조작 언어인 GraphQL은 기존의 RESTful 접근 방식에서 중요한 변화를 나타냅니다.

GraphQL의 개념:
1. API용 쿼리 언어: GraphQL을 사용하면 클라이언트가 필요한 데이터를 정확히 지정할 수 있으므로 한 번의 요청으로 다양한 데이터를 가져올 수 있습니다.
2. 타입 시스템: 강력한 타입 시스템을 사용하여 API의 기능을 정의합니다. API가 제공하는 모든 유형은 스키마에 기록됩니다.
3. 구독을 통한 실시간 데이터 : GraphQL은 실시간 데이터 업데이트를 지원하므로 즉각적인 데이터 반영이 필요한 동적 사용자 인터페이스 및 애플리케이션에 이상적입니다.

GraphQL의 장점:
1. 효율적인 데이터 검색: 클라이언트는 필요한 데이터만 정확하게 요청할 수 있습니다. 이러한 효율성은 네트워크 트래픽을 줄이고 응답 시간을 단축합니다.
2. 단일 엔드포인트: 관련 리소스를 가져오기 위해 여러 개의 엔드포인트가 필요할 수 있는 REST와 달리, GraphQL은 단일 엔드포인트를 사용해 모든 쿼리를 처리합니다.
3. 강력한 유형화: 모든 데이터 모델이 특정 유형과 연결되어 있어 개발 시 예측 가능성과 견고성이 향상됩니다.
4. 개발자 환경: GraphQL은 쿼리를 탐색하고 테스트할 수 있는 대화형 환경(예: GraphiQL)을 제공하여 개발자 환경을 개선합니다.

REST와의 차이점:
1. 데이터 가져오기: REST는 일반적으로 관련 리소스를 수집하기 위해 여러 개의 엔드포인트가 필요하지만, GraphQL은 단일 쿼리로 필요한 모든 데이터를 가져올 수 있습니다.
2. 오버 페칭 및 언더 페칭: RESTful 서비스는 종종 오버 페칭(필요 이상의 데이터를 가져오는 것) 또는 언더 페칭(추가 요청이 필요한 것)으로 이어집니다. GraphQL은 정확한 쿼리를 허용하여 이 문제를 해결합니다.
3. 유연성 대 표준화: GraphQL은 데이터를 쿼리할 때 더 많은 유연성을 제공하는 반면, REST는 리소스 엔드포인트에 대해 더 표준화된 접근 방식을 제공합니다.

요약하자면, API 쿼리에 대한 GraphQL의 고유한 접근 방식은 특히 유연성과 효율적인 데이터 검색이 핵심인 시나리오에서 상당한 이점을 제공합니다. REST와의 차이점은 강력한 쿼리 기능을 통해 개발자가 보다 효율적이고 맞춤화된 API 상호 작용을 만들 수 있다는 점입니다.