API 구축 방법
2022년 6월 30일
API란 무엇인가요?
API란 무엇이고, API를 성공적으로 구축하기 위한 가이드라인은 무엇일까요? 애플리케이션 프로그래밍 인터페이스(API)는 외부 애플리케이션이 플랫폼, 운영 체제, 애플리케이션, 서비스 등의 기능 또는 데이터에 액세스하고 상호작용할 수 있도록 지원하는 프로그래밍 기능, 도구, 프로토콜의 집합입니다. 효과적인 API는 대규모 데이터 공유 및 협업의 통로가 되어 서로 다른 소프트웨어들이 서로 통신하며 하나의 비즈니스 기능을 함께 제공하는 생태계를 조성합니다. API는 현대 애플리케이션과 클라우드 네이티브, 마이크로서비스 기반 아키텍처의 핵심 구성 요소로서 서로 다른 서비스들이 서로 통신하며 함께 현대적인 경험을 제공하는 주요 채널을 구축합니다.
성공적인 API 설계, 개발, 배포를 위해서는 다양한 모범 사례를 활용해야 합니다. 관련 모범 사례들을 준수함으로써 개발자와 애플리케이션 모두에게 안전한 액세스 및 쉬운 사용을 보장하는 프로세스를 구축할 수 있습니다. 모범 사례는 다음과 같습니다.
- 기술 수준과 경험이 서로 다른 모든 개발자들이 API를 활용할 수 있는 단순하고 우아한 설계
- 필요한 경우 데이터 액세스를 제한할 수 있는 높은 수준의 보안성
- API 액세스가 소스 애플리케이션이나 외부 애플리케이션의 성능을 저하시키지 않는 간결한 설계 원칙
- 기존 API에 대한 거버넌스, 보안, 사용량 모니터링을 보장하는 관련 서비스
API를 처음부터 개발하는 방법
API의 구축 방식은 데이터 소스 자체 및 해당 소스와 인터페이스할 외부 애플리케이션(들)과 관련된 특정한 요소들에 따라 결정됩니다. API 개발 프로세스를 계획하는 과정에서 던져 보아야 할 질문들은 다음과 같습니다.
목표는 무엇인가요?
어떤 유형의 프로젝트든 가장 좋은 시작점은 항상 큰 그림, 즉 목표를 정의하고 이해하는 것입니다. API의 목적은 개발 프로젝트의 길잡이 역할을 합니다. API를 통해 어떤 정보를 교환할 것인가요? 교환한 정보는 어떻게 사용 또는 제공하나요? 고려해야 할 다른 요소로는 애플리케이션의 대상 고객과 그들의 요구 사항을 이해하는 것 등이 있습니다.
제한 사항은 무엇인가요?
프로젝트 목표의 반대편에는 프로젝트 제한 사항이 있습니다. 실용적인 시각을 적용하는 것은 개발 과정의 필수적인 단계로서 개발팀은 가용 자원 및 일정상의 제한 사항을 잘 이해하고 있어야 합니다. 또 다른 고려 사항으로서 보안 문제, 하드웨어 자원 영향, 확장성 요구 시 성능 요구 사항 등의 기술적 제약 조건 여부를 함께 확인해야 합니다.
귀사의 아키텍처는 무엇인가요?
개발자는 API를 처음부터 설계하는 과정에서 다양한 시작점을 선택할 수 있습니다. Python, Java, JavaScript, C# 등의 다양한 언어로 API를 개발할 수 있습니다. 설계 고려 사항에 따라 구축해야 하는 다른 요인으로는 사용성, 확장성(리소스 요구 사항과 연계), 보안 등이 있습니다. API는 애플리케이션 간의 가교 역할을 수행하므로 개중에서도 보안은 매우 중요합니다. 안전성을 확보하기 위해서는 반드시 양측 모두의 데이터를 적절히 보호해야 합니다. 보안 취약점이 있는 API는 코드 삽입이나 데이터 노출 같은 악용에 노출될 수 있습니다.
개발자는 API를 처음부터 구축하는 과정에서 이상의 큰 질문들을 통해 가이드라인을 정의하고 세부적인 작업에 더 깊이 몰입할 수 있습니다.
SOAP API vs. REST API
API를 설계할 때 핵심적인 결정 사항 중 하나는 애플리케이션이 웹 서비스에 액세스하는 방식입니다. 소프트웨어 아키텍처 스타일인 단순 객체 접근 프로토콜(SOAP)과 표현 상태 전이(REST) 모두 API 설계를 위한 효과적인 경로가 될 수 있습니다. 양쪽 모두 장단점이 있으며, 프로젝트에 가장 적합한 방식이 어느 쪽일지는 사용 상황과 맥락에 따라 달라집니다. 대부분의 웹 서비스는 일반적으로 SOAP 또는 REST 중 한 쪽을 지원하므로 API에 어떤 웹 서비스를 사용할지는 개발 목표에 SOAP과 REST 중 어느 쪽이 더 적합한지에 따라 결정될 수 있습니다
SOAP란 무엇인가요?
SOAP는 Microsoft에서 설계한 XML 기반 프로토콜입니다. 일련의 규칙을 중심으로 구축된 SOAP는 수많은 확장(WS-coordination 및 WS-security), 자동화, 내장된 오류 처리를 지원해 온 메시징 표준들의 근간이 되었습니다. SOAP는 분산 환경에서 가장 효과적이지만, XML 구조에 대한 의존성으로 인해 코드가 지나치게 복잡해질 수 있습니다.
REST란 무엇인가요?
REST는 SOAP에 비해 더 단순하고 가벼운 대안으로 개발되었으며, 포인트 투 포인트 레벨에서 작동합니다. 효율적인 확장성을 위해 특별히 설계된 소프트웨어 아키텍처 스타일로서 유연성을 제공하면서도 처리량을 최소화하는 일련의 표준화된 제약 조건을 제공합니다. REST의 빠른 응답성은 JSON 및 CSV 등의 애플리케이션이 사용하는 다양한 출력 메시지 형식 전반에 걸친 지연 시간을 최소화합니다.
API 개발에 REST와 SOAP 중 어느 쪽을 선택해야 할까요?
귀사의 애플리케이션에 가장 적합한 표준은 무엇일까요? 정답은 귀사의 요구 사항에 따라 달라집니다. 공유 미디어나 데이터베이스 쿼리 출력을 비롯해 애플리케이션이 단순한 사용자 대상 메시지를 제공하는 경우 대부분 REST API가 적합한 선택입니다. SOAP는 학습 및 사용 난이도가 높지만, 그와 같은 본질적인 복잡성에 힘입어 보안 결제 같은 더 복잡한 트랜잭션을 처리할 수 있습니다.
API 설계 도구 선택하기
API 구축의 세부 사항은 개발팀이 선택한 도구에 따라 달라집니다. Oracle Cloud Infrastructure(OCI)의 API 솔루션은 개발팀이 OpenAPI 사양을 기반으로 신속한 프로토타이핑 및 검증이 가능한 완벽한 툴킷을 활용해 API를 간단히 설계하고 개발할 수 있도록 지원합니다. OCI 사용자는 API Blueprint 또는 Swagger에 액세스하여 API를 설계할 수 있습니다. 또한 API를 처음부터 새로 만들거나 템플릿을 활용하여 개발 프로세스를 가속화할 수도 있습니다.
OCI에서의 API 개발 프로세스를 자세히 살펴보겠습니다. 이 예시에서는 OCI 콘솔을 사용하여 API 리소스를 생성합니다(업로드된 API 설명 파일에서 생성된 API 설명을 선택적으로 사용할 수도 있습니다). 무료 OCI 계정을 생성하고 아래의 단계를 직접 수행해 보세요.
- 콘솔에서 탐색 메뉴를 열고 Developer Services를 클릭합니다. API Management 아래의 Gateways를 클릭합니다.
- API 페이지에서 Create API Resource를 누르고 Name을 지정합니다. 지원되는 언어로 작성된 API 설명이 포함된 API 설명 파일과 태그를 업로드합니다.
- Create를 눌러 새 API 리소스를 생성합니다.
- 백엔드 코드를 작성합니다. 선호하는 프로그래밍 언어와 프레임워크를 사용하여 API를 구동할 백엔드 코드를 작성합니다. 이는 다른 협력자와 함께 진행하는 반복적인 과정이 될 수 있습니다.
- 백엔드 코드를 테스트합니다. Oracle의 API 개발 서비스는 로컬 및 다양한 지속적 통합(CI) 서비스를 통한 테스트를 지원하는 여러 도구를 제공합니다.
- 배포합니다. API를 출시하고 개발자 생태계, 파트너, 고객, 내부 개발자가 액세스할 수 있도록 합니다. Oracle API Gateway는 API 연결, 보안, 거버넌스 관련 사용 모니터링 및 관리를 지원합니다.
Oracle의 클라우드 기반 API 솔루션을 사용한 API 개발에 대한 자세한 내용은 Oracle API 개발자 가이드(PDF)를 참고하세요.
API 테스트 모범 사례
API의 철저한 테스트는 원활한 실행 및 지속적인 운영을 보장하는 중요한 단계입니다. 귀사의 비즈니스 요구 사항을 충족하는 API를 배포하는 데 도움을 줄 효과적인 API 모범 사례는 다음과 같습니다.
- API 스모크 테스트(기본 기능만 검증하는 최소한의 테스트)를 통해 코드를 검증하세요. 스모크 테스트를 통해 반복적으로 발생하는 오류를 확인해야 합니다.
- 운영 환경과 유사한 조건에서 현실적인 데이터를 사용합니다. 실제 사용 사례를 반영하지 않는 데이터로 작업하면 다양한 시나리오에 대한 문제 해결 능력을 갖추는 과정이 길어질 뿐만 아니라 테스트 결과의 신뢰도가 저하될 수 있습니다. 따라서 테스트는 가능한 한 실제 시나리오를 재현해야 합니다.
- 긍정적 테스트와 부정적 테스트를 모두 수행합니다. 테스트를 통해 예상되는 결과와 사용 시나리오의 전체 스펙트럼을 확보해야 하므로 개발자는 긍정적 테스트(예상되는 기능적 결과)와 부정적 테스트(계획된 오류가 야기하는 예상치 못한 결과)를 모두 고려해야 합니다.
- API 응답을 포괄적으로 추적해 투명한 결과 데이터를 확보합니다. 테스트는 길고 힘든 과정일 수 있으며, 테스트 결과 데이터가 방대할 경우 폐기하고 싶은 충동이 드는 것은 자연스러운 일입니다. 그러나 테스트 데이터를 성실히 기록하면 기능, 동작, 테스트 결과 및 효과에 대한 명확한 기록을 얻을 수 있습니다.
- 보안 및 성능을 모두 점검합니다. 기능성은 물론 핵심 요소이지만, 테스트를 통해 정상 작동을 입증한 뒤에는 보안(데이터 및 액세스 위험)과 성능(자원 사용량, 확장성, 효율적 처리)을 점검하는 것도 그에 못지 않게 중요합니다.
API를 구축 및 테스트할 준비가 되셨나요? Oracle Cloud Infrastructure(OCI) API 관리 서비스 무료 체험을 통해 완전한 API 수명 주기 관리 솔루션을 직접 경험해 보세요.