API 성숙도 모델이란 무엇인가요?

일부 API 성숙도 프레임워크는 보안, 발견 가능성, 유지보수성 또는 플랫폼 엔지니어링과 같은 특정 요소를 강조합니다. Kong, Tyk, Curity를 포함한 API 관리 공급자는 자사 솔루션에 맞춘 API 성숙도 모델을 제공하여 고객이 해당 플랫폼 도입 진행 상황을 평가할 수 있도록 지원합니다. 다른 모델은 더 넓은 범위를 다루며 어떤 프로토콜이나 아키텍처에도 적용할 수 있습니다.

애플리케이션 프로그래밍 인터페이스(API)는 서로 다른 서비스와 애플리케이션 간의 연결을 가능하게 하는 인터넷의 핵심 요소로, 개발자가 처음부터 구축하는 대신 타사 기술과 데이터 소스를 활용할 수 있도록 지원합니다. 또한 조직 내 리소스, 데이터, 보안 및 거버넌스의 통합을 가능하게 하여 내부 배포와 팀 간 커뮤니케이션을 간소화합니다. 여러 API는 라이브러리, UI 툴 및 기타 구성 요소와 함께 패키지화되어 소프트웨어 개발 키트(SDK)를 구성할 수 있으며, 이는 개발자가 표준화된 애플리케이션을 빠르고 안정적으로 구축할 수 있도록 지원하는 툴 세트입니다.

API 성숙도 모델은 조직이 보다 정교하고 견고한 API 시스템을 구축할 수 있도록 지원하는 구조적 및 기술적 혁신과 함께 전략적 모범 사례를 식별하고 설명하며, 이를 통해 효율성, 보안 및 상호운용성을 개선합니다. 이 모델은 조직이 API 개발을 가속화하는 과정에서 어떤 혁신에 우선순위를 둘지 결정하는 데 도움이 되는 로드맵 역할을 합니다.

가장 널리 인용되는 프레임워크 중 하나인 Richardson 성숙도 모델은 API가 RESTful 원칙을 얼마나 준수하는지를 네 가지 성숙도 단계로 평가하며, 가장 높은 단계는 완전한 RESTful 시스템을 의미합니다.

2000년에 컴퓨터 과학자 Roy Fielding은 REST를 소개했으며, 이는 일관된 인터페이스, 클라이언트-서버 분리, 무상태성, 캐시 가능성 및 계층형 시스템과 같은 특성을 강조하는 아키텍처 스타일입니다. 이러한 기능은 함께 조직 내 확장성, 효율성 및 유연성을 향상시킬 수 있으며, 대규모로 구현될 경우 보다 개방적이고 탄력적이며 안전한 인터넷 환경 구축에 기여할 수 있습니다. 현대의 구현 방식은 정보를 전달하기 위해 HTTP를 사용하고 데이터를 구성하기 위해 사람이 읽기 쉬운 JSON 형식을 사용하는 경우가 많지만, 다른 프로토콜과 형식도 사용할 수 있습니다.

2008년에 소프트웨어 엔지니어 Leonard Richardson은 이 프레임워크를 확장하여 조직이 REST API 설계의 적응성과 복원력을 개선하기 위해 구현할 수 있는 구체적인 기술적 변화를 식별하는 모델을 제시했습니다. Richardson은 IBM Think와의 인터뷰에서 Richardson 성숙도 모델(RMM)이 "URI, HTTP 및 하이퍼미디어(HTML이라고도 함)라는 세 가지 웹 기술을 하나의 패키지가 아니라 각각의 개별 기술로 바라보도록 권장한다"고 설명했습니다. 이 프레임워크는 이러한 기술이 이미 매우 널리 사용되고 대부분의 프로그래밍 언어에서 지원된다는 점을 고려할 때, 각각을 점진적으로 구현함으로써 얻을 수 있는 실질적인 이점을 보여줍니다.

Richardson 성숙도 모델은 각 리소스에 고유한 URI를 부여하는 리소스 구현을 우선시하며, 이는 각 리소스에 고유 식별자를 할당해야 한다는 일반적인 REST 원칙에 부합합니다. 또한 RMM은 특정 시점의 정적인 API 설명을 제공하는 설명 문서 대신, API의 현재 상태를 반영하는 응답 문서 사용을 권장합니다. 이 모델은 일반적으로 HTTP 기반 웹 애플리케이션에 적용되지만, 개념적 프레임워크로서 IoT 네트워크나 데이터 파이프라인과 같은 다른 컨텍스트에도 활용할 수 있습니다.

Richardson 성숙도 모델은 비RESTful 아키텍처부터 완전한 RESTful 아키텍처까지 다양한 성숙도 수준을 구분하기 위해 네 가지 단계를 사용합니다.

레벨 0은 단일 엔드포인트(예: "/api")와 단일 명령(일반적으로 POST)을 사용하는 비RESTful 설계를 의미합니다. 레벨 0은 구현이 간단하지만, HTTP의 주요 기능인 메서드, URI 및 상태 코드를 활용하지 못합니다. 대신 HTTP는 단순한 전송 수단으로만 사용되며, 모든 작업 관련 정보는 메시지 본문에 포함됩니다.

XML 기반 원격 프로시저 호출(RPC) 패턴이 역사적으로 이 방식을 사용해 왔기 때문에, 비판가들은 이를 "swamp of POX"(plain old XML)라고 부릅니다. 이 개념은 구조가 부족하고 서비스, 기능 및 데이터 간 경계가 명확하지 않기 때문에 요소들이 쉽게 뒤섞이고 강하게 결합될 수 있다는 의미입니다. 레벨 0에서는 API가 발견 가능한 리소스를 식별하거나 노출할 수 없기 때문에, API 사용자는 무엇이 제공되는지 사전에 알아야 합니다. 단일 엔드포인트는 자체 정보를 제공할 수 없기 때문에 개발자는 확장, 버전 관리 및 문제 해결에 어려움을 겪을 수 있습니다.

레벨 1에서는 서로 다른 리소스를 나타낼 수 있는 여러 URI가 도입됩니다. 하지만 여전히 단일 HTTP 메서드(일반적으로 POST)만 사용합니다. 클라이언트는 더 이상 일반적인 "/api" 엔드포인트가 아니라 특정 리소스에 대응하는 엔드포인트(예: 이커머스 환경에서 "/products", "/carts", "/invoices")를 호출할 수 있습니다. 그러나 클라이언트는 여전히 사전에 정의된 HTTP 메서드를 사용하는 대신 요청 본문을 통해 작업 의도나 동작을 전달해야 합니다.

이 접근 방식은 리소스 간 경계를 보다 명확하게 하고, 클라이언트가 사용할 수 있는 리소스에 대한 모호성을 줄입니다. 하지만 URI 호출 방식에 대한 표준이 없기 때문에 어떤 작업을 수행할 수 있는지 개발자가 혼동하기 쉽습니다. 또한 실제로 개발자가 "/productsUpdate"나 "/productsDelete"와 같은 개별 작업용 엔드포인트를 생성할 수 있기 때문에 레벨 1은 시간이 지남에 따라 복잡해질 수 있습니다. 이러한 접근 방식은 URI가 점점 늘어나게 만들어 배포와 버전 관리를 더욱 어렵게 할 수 있습니다.

또한 이 모델은 리소스에 고유한 URI가 할당되더라도 수행 가능한 작업을 노출할 수 없기 때문에 개발자가 외부 API 문서에 더 의존하게 만듭니다.

레벨 2에서는 개발자가 데이터와 서비스와 상호작용할 수 있도록 표준화된 HTTP 메서드를 추가합니다. 많은 구성에서 클라이언트는 생성, 조회, 수정, 삭제의 네 가지 기본 명령을 사용하여 각 엔드포인트에서 다양한 작업을 수행할 수 있습니다. API 호출 시 헤더를 사용하여 콘텐츠 유형, 조건 요구 사항 또는 인증 자격 증명과 같은 추가 정보를 전달할 수 있습니다.

이 접근 방식은 사용자가 API의 기능과 클라이언트와의 상호작용 방식을 이해할 수 있기 때문에 레벨 1 및 레벨 0에 비해 더 효율적이고 체계적입니다. 하지만 API는 이러한 정보를 실시간으로 전달할 수 없으며, 사용자는 외부 개발자 포털을 통해서만 API를 이해할 수 있기 때문에 발견 가능성이 낮아집니다. 또한 이와 같은 정적인 접근 방식은 API 문서가 현재 기능과 일치하지 않을 경우 불일치를 초래할 수 있습니다.

오늘날 대부분의 조직의 API 에코시스템은 예측 가능성, 효율성 및 접근성 간의 균형을 제공하기 때문에 레벨 2에서 운영됩니다. 또한 캐싱(자주 사용하는 리소스를 로컬에 저장하여 빠르게 가져올 수 있도록 하는 기능)과 같은 HTTP의 고유한 인프라 기능을 활용할 수 있어 성능을 크게 향상시킬 수 있습니다.

레벨 3에서는 애플리케이션 상태의 엔진으로서 하이퍼미디어를 의미하는 HATEOAS가 도입됩니다. 클라이언트가 API를 호출하면 API는 최신 브라우저처럼 다양한 작업과 관련 항목에 대한 동적 옵션 목록으로 응답합니다. 이러한 작업과 정보는 인밴드 방식으로 전달되므로 개발자는 이를 이해하기 위해 외부 문서를 참고할 필요가 없습니다. 하이퍼미디어 기반 아키텍처는 외부 클라이언트가 사전에 사용 방법을 학습하지 않고도 서비스를 쉽게 이용할 수 있기 때문에 상호운용성을 향상시킵니다.

동시에 하이퍼미디어 제어는 런타임에서 더 큰 복잡성을 야기합니다. Richardson은 "클라이언트는 사전에 프로그래밍된 방식으로 반응하는 것뿐만 아니라 서버에서 전달되는 문서를 읽고 그 내용을 기반으로 다음 요청을 결정할 수 있어야 한다"고 설명했습니다.

하이퍼미디어의 동적인 구조로 인해 하이퍼미디어 기능을 구축하고 유지하는 데 더 많은 비용과 시간이 소요될 수 있습니다. API는 클라이언트 요청에 대해 추가 작업을 위한 링크 집합으로 응답하므로 운영 부담이 더 큽니다. 또한 많은 클라이언트 플랫폼이 하이퍼미디어를 지원하지 않기 때문에 조직이 HATEOAS를 도입할 경우 외부 사용자는 이러한 서비스를 이용하기 전에 호환되는 툴을 찾아야 할 수 있습니다.

Richardson에 따르면 HATEOAS는 개방성과 상호운용성을 촉진하기 때문에 오늘날 도서관, 비영리 단체, 과학 기관, 시장 연합 또는 산업을 혁신하려는 신생 기업에서 주로 사용됩니다. 하이퍼미디어는 내부적으로 사용할 때도 효과적이며, API 에코시스템에 대한 사전 지식이 없는 사용자라도 API와 작업을 쉽게 발견할 수 있도록 합니다. 일부 기업은 성장 단계에서 하이퍼미디어 API를 제공하다가 제품 수익화가 시작되면 접근을 제한하기도 합니다.

업계는 특정 사용 사례에 대해 GraphQL과 gRPC와 같은 대안으로 점점 이동하고 있습니다. Postman의 State of the API 보고서에 따르면 개발자의 93%가 어떤 형태로든 RESTful 웹 서비스를 사용하고 있으며, 현재 3분의 1은 GraphQL을, 14%는 gRPC를 사용하고 있습니다. GraphQL은 서로 다른 환경에서 호스팅된 서비스까지 포함한 여러 마이크로서비스에서 요청을 지능적으로 가져와 하나의 응답으로 결합함으로써 효율성을 높이고 과도하거나 부족한 리소스 할당을 방지할 수 있습니다. 한편 gRPC는 스트리밍, 텔레메트리 및 고성능과 저지연이 중요한 사용 사례에 적합합니다.

GraphQL과 gRPC는 하이퍼미디어의 동적인 특성을 그대로 구현할 수는 없지만, 두 아키텍처 모두 효율성과 스키마 관리 관련 문제를 보다 정밀하게 해결하여 일부 조직에서는 완전한 하이퍼미디어 제어보다 이러한 구현을 우선시하게 만듭니다.

Richardson 성숙도 모델에서는 한 API 성숙도 단계에서 다음 단계로 이동하는 과정에서 설계 및 기술적 과제가 모두 발생할 수 있습니다. 이 과정에는 여러 URI(레벨 1)와 여러 HTTP 메서드(레벨 2)를 지원하도록 서버 코드를 리팩토링하는 작업이 포함되는 경우가 많습니다. 이는 라우팅 규칙, 데이터베이스 상호작용, 테스트, 문서 및 컨트롤러를 업데이트하여 수행됩니다.

조직은 현재 엔드포인트를 목록화하고 RESTful 제약을 따르도록 수정 가능한 항목을 식별하며 필요한 리소스와 메서드를 매핑하는 작업부터 시작할 수 있습니다. 개발자는 전환 과정에서 클라이언트 호출이 중단되지 않도록 기존 빌드 위에 새로운 버전을 구축할 수 있습니다. 포괄적인 오류 코드 세트는 사용자가 과도한 문서를 참고하지 않고도 새로운 API 엔드포인트를 탐색하고 오류를 해결하는 데 도움을 줄 수 있습니다.

RMM이 RESTful 시스템의 특정 기술적 구현에 초점을 맞추는 반면, 조직 모델은 보다 넓은 관점을 취하여 일관성, 리소스 최적화 및 적응성을 촉진하는 공통 원칙에 맞춰 기업이 정렬되도록 돕습니다. 전략적 성숙도 프레임워크는 조직마다 다를 수 있지만, 일반적으로 네 가지 단계로 구성되는 접근 방식이 널리 사용됩니다.

기초적이거나 임시적인 API 에코시스템에서는 조직이 일관된 API 개발 프레임워크 없이 즉각적인 문제에 대응하는 방식으로 운영됩니다. 개발자는 제한된 중앙 통제 하에서 필요에 따라 API를 생성하고 폐기하며, 이는 불일치뿐 아니라 거버넌스, 보안 및 관측 가능성 문제를 초래할 수 있습니다. 현재 API 성능에 대한 가시성이 부족하면 팀은 리소스를 효과적으로 배분하거나 미래를 계획하기 어렵습니다.

표준화된 API 에코시스템은 일관된 문서화, 명명 규칙, 오류 코드 및 설계 패턴을 도입합니다. API 게이트웨이는 인증, 권한 부여 및 기타 중앙 집중식 API 보안 프로토콜을 적용하는 데 사용될 수 있습니다. 개발자는 조직의 거버넌스 구조 내에서 API를 자신 있게 추가, 제거 및 유지 관리할 수 있으며 구성 요소를 원활하게 재사용하고 조정할 수 있습니다. 클라이언트는 개발자 포털과 통합 온보딩을 통해 제공되는 서비스를 쉽게 발견하고 이해할 수 있어 전체 API 도입률이 증가합니다.

하지만 이 단계에서는 API 성능과 보안을 측정할 수 있는 메커니즘이 부족하기 때문에 팀이 에코시스템을 효과적으로 관리하는 데 어려움을 겪을 수 있습니다. 예를 들어 조직은 특정 API 클러스터 내에서 발생한 보안 침해, 버전 오류 또는 인증 문제를 인지하지 못할 수 있습니다.

관리형 프레임워크는 텔레메트리 데이터, 핵심 성과 지표(KPI) 및 기타 지표를 활용하여 API 성능을 보다 상세하게 파악합니다. 예를 들어 모니터링 시스템은 클라이언트가 과도한 API 다운타임을 겪을 때 개발자에게 알림을 보내고, 서버 과부하, 네트워크 장애, 코드 불일치 또는 기타 문제 등 근본 원인을 식별하는 데 도움을 줄 수 있습니다.

관리형 에코시스템은 팀의 자율성을 유지하면서도 이해관계자가 어떤 API를 관리해야 하는지 명확히 이해할 수 있도록 보다 고도화된 API 거버넌스 인프라를 갖출 수 있습니다. 또한 관리형 에코시스템은 설계, 개발, 유지보수, 버전 관리 및 폐기에 이르는 전 과정에서 API를 모니터링하는 공식적인 라이프사이클 관리 프로세스를 도입합니다. 하지만 이 단계에서는 API 관리가 보다 넓은 비즈니스 목표에 어떻게 기여하는지에 대한 일관된 비전이 부족할 수 있습니다.

최적화 또는 전략적 프레임워크는 거버넌스, 표준화, 라이프사이클 관리, 지표 및 보안 모범 사례를 장기적인 비즈니스 계획과 결합합니다. 전체 네트워크에 대한 가시성을 확보함으로써 조직은 효율적으로 확장하고 리소스를 배분하며 변화하는 시장 상황에 유연하게 대응할 수 있습니다. 조직은 API를 단순한 기술 구성 요소로 보는 대신 보다 넓은 비즈니스 목표를 달성하기 위한 수단으로 활용할 수 있습니다. 전략적 프레임워크는 조직이 미래 지향적인 로드맵과 계획 전략을 수립하도록 지원하여 혁신을 가속화하고 운영 효율성을 개선합니다.

조직은 특정 문제점이나 운영상의 중점 영역을 해결하기 위해 API 성숙도 모델을 설계할 수 있습니다. 일반적인 중점 영역은 다음과 같습니다.

이러한 성숙도 모델은 사용자 경험 향상에 기여하는 특정 프로토콜, 관행 및 표준을 채택하는 등 API 설계 원칙에 초점을 맞춥니다. RMM은 설계 기반 프레임워크의 한 예이며, 다른 모델은 GraphQL, gRPC 및 기타 아키텍처 스타일에 초점을 맞출 수 있습니다.

거버넌스 모델은 조직이 API 에코시스템에 대해 어느 정도의 통제력과 관리 감독을 유지할 수 있는지에 초점을 맞춥니다. 최상위 단계에서는 이해관계자의 자율성을 유지하면서도 높은 수준의 규정 준수, 데이터 품질 및 보안을 확보합니다.

거버넌스 기반 프레임워크는 자동화된 점검 및 검증 프로세스를 포함하는지 여부 등 API 에코시스템의 집행 메커니즘의 품질도 고려합니다. 한편 소유권 모델은 API를 특정 팀에 할당하여 모든 API의 책임 주체를 명확히 합니다.

보안 중심 성숙도 프레임워크는 API 네트워크가 보안 모범 사례를 얼마나 준수하는지를 평가합니다. 초기 단계에서는 조직이 세분화된 제어가 부족하고 노출 위험이 있는 API 키 또는 기본 HTTP 인증에 의존할 수 있습니다. 고급 시스템에서는 토큰 기반 인증 및 권한 부여와 함께 제로 트러스트 액세스를 도입할 수 있습니다. 가장 정교한 프레임워크는 ID 및 액세스 관리 원칙을 따르며, OAuth 및 OpenID Connect(OIDC) 권한 부여 프로토콜을 사용하는 방식이 이에 해당합니다.

API 문서는 개발자가 특정 API를 사용하는 방법과 통합하는 방법에 대한 지침을 제공하는 기술 문서입니다. 문서에는 튜토리얼과 코드 예제뿐 아니라 릴리스 노트 및 허용되는 호출 파라미터도 포함될 수 있습니다.

초기에는 API 문서를 생성하고 유지하기 위한 표준화된 프로세스가 없어 개발자가 각 API의 기능을 충분히 이해하기 어려울 수 있습니다. 상위 단계에서는 OpenAPI Specification(OAS) 또는 API Blueprint와 같은 API 사양을 설명하기 위한 표준 형식을 도입할 수 있습니다. 성숙한 API 프레임워크는 자동화를 도입하여 각 배포와 함께 문서가 자동으로 업데이트되도록 할 수 있습니다.

관측 가능성 중심 성숙도 모델은 조직이 마이크로서비스 전반에서 데이터 수집 메커니즘의 정교함을 추적하도록 지원합니다. 기본 시스템은 텔레메트리와 지표를 사용하여 조직이 오류를 식별하는 데 도움을 줄 수 있지만, 장기적인 데이터 추세를 파악하는 데는 한계가 있습니다.

보다 복잡한 플랫폼은 지연 시간, 요청 비율 및 기타 관련 지표를 선제적으로 추적하여 조직이 다운타임, 불일치 및 기타 문제에 사전에 대응할 수 있도록 지원합니다. 최상위 단계에서는 조직이 고수준 데이터 패턴을 식별하고 향후 API 개발을 이끄는 실행 가능한 인사이트를 도출할 수 있습니다.