API 검색을 위해 API 개발자 포털이 필요한 이유

Andrew Stiefel

기업은 여러 사업 부문의 애플리케이션과 데이터를 연결하고, 파트너와 통합하며, 고객 경험을 제공하기 위해 API에 점점 더 의존하고 있습니다. TechRadar에 따르면, 오늘날 기업은 평균적으로 총 15,564개의 API를 활용하고 있으며, 이는 전년 대비 201% 증가한 수치입니다.

API 수가 계속 증가함에 따라, API 포트폴리오 관리의 복잡성도 커집니다. 어떤 API를 사용할 수 있고 어디에 있는지 파악하고 추적하는 것은 물론, 사용 방법에 관한 문서를 찾기도 점점 어려워집니다. 종합적인 API 전략이 없으면 플랫폼 운영 팀이 관리할 수 있는 속도보다 더 빠르게 API가 늘어날 수 있습니다. 이러한 문제를 API 스프롤이라고 하며, 이전 게시물에서는 이것이 왜 그토록 심각한 위협인지 설명했습니다. 이 게시물에서는 NGINX를 활용해 API 개발자 포털을 구축함으로써 API 스프롤에 대응하는 방법을 자세히 살펴봅니다.

API 인벤토리 구축

궁극적으로 API는 실제로 사용되어야만 가치를 발휘할 수 있습니다. 즉, API 소비자가 필요한 API를 찾을 수 있는 방법이 있어야 합니다. 적절한 시스템이 마련되어 있지 않으면 API가 무분별하게 확산되어 개발자가 애플리케이션에 필요한 API를 찾기 어려워집니다. 그나마 나은 경우에도 각 사업 부문에서 API 목록을 별도로 관리하고, 엔지니어들의 비공식 네트워크를 통해 팀 간에 지식을 공유하는 수준에 그칩니다.

API 난립을 방지하기 위한 첫 단계 중 하나는 API에 대한 단일 정보 소스를 구축하는 것입니다. 이 과정은 API 목록을 작성하는 것에서 시작됩니다. 하지만 정확한 목록을 유지하기는 쉽지 않습니다. 새로운 API가 도입되고 기존 API가 폐기됨에 따라 목록이 끊임없이 변하기 때문입니다. 또한 시간이 지나면서 잊혔거나, 부적절하게 폐기되었거나, 표준 프로세스를 벗어나 구축된 API인 ‘섀도 API’가 환경 전반에 존재하는지도 찾아내야 합니다.

관리되지 않는 API는 API 난립의 가장 심각한 징후 중 하나로, 명백한 보안 문제뿐 아니라 숨겨진 비용까지 초래합니다. 사용 가능한 API의 정확한 목록이 없으면 API 팀은 문서를 찾는 데 시간을 허비해야 합니다. 여러 팀이 유사한 기능을 각각 구축하면서 불필요하게 작업이 중복될 위험도 큽니다. 또한 적절한 버전 관리 없이 특정 API를 변경하면 연쇄적인 재작업으로 막대한 비용이 발생하거나 서비스 중단으로까지 이어질 수 있습니다.

자동화된 API 검색과 같은 기법을 활용하면 관리되지 않는 API라는 증상을 식별하고 해결할 수 있습니다. 하지만 문제를 근본적으로 해결하려면 제대로 작동하지 않는 프로세스와 소유권 부재라는 근본 원인을 제거해야 합니다. 실제로 API 인벤토리와 문서화를 CI/CD 파이프라인에 통합하는 것이 장기적으로 전체 API 포트폴리오의 가시성을 보장하는 유일한 방법입니다. 새로 가동되는 모든 API를 일일이 추적하는 대신 예외 사항만 식별하여 해결하면 됩니다.

API 개발자 포털로 API 검색 간소화

API 개발자 포털은 API 검색 프로세스를 간소화하는 데 도움이 될 수 있습니다. API 소비자는 이 중앙 공간에서 API를 검색하고 문서를 읽으며, 애플리케이션에 통합하기 전에 API를 직접 사용해 볼 수 있습니다. 또한 API 개발자 포털은 소유권 및 연락처 정보가 포함된 중앙 API 카탈로그 역할도 할 수 있으므로, 누구나 각 서비스의 API 유지 관리를 담당하는 사람이 누구인지 알 수 있습니다.

당사의 API 참조 아키텍처<.htmla>의 핵심 구성 요소인 효과적인 API 개발자 포털은 다음과 같은 몇 가지 주요 사용 사례를 지원합니다:

• API 검색 간소화 – 개발자가 프로젝트에서 API를 쉽게 찾고 사용할 수 있도록 접근하기 쉬운 위치에 API를 게시하세요.
• 명확한 최신 문서 제공 – 개발자가 API의 작동 방식에 관한 최신 문서에 항상 액세스할 수 있도록 합니다
• 적절한 버전 관리 보장 – 버전 관리를 지원하여 다운스트림 애플리케이션의 중단 없이 새로운 API 버전을 도입합니다
• API 자격 증명 생성 – 개발자가 로그인하여 API 액세스에 사용할 자격 증명을 생성할 수 있도록 온보딩 프로세스를 간소화합니다
• API 사용해 보기 – 개발자가 프로젝트에 API를 통합하기 전에 포털에서 직접 사용해 볼 수 있도록 지원합니다

API 전략의 일환으로 API 개발자 포털을 유지 관리하는 방법을 마련해야 합니다. API 팀의 업무 부담을 늘리지 않으면서 API 게시, 버전 관리 및 문서화를 원활하게 통합하는 자동화된 최소 개입 방식이 필요합니다.

NGINX로 API를 위한 단일 정보 소스 구축

원활한 API 검색을 지원하려면 개발자가 API를 찾고, 사용 방법을 익히며, 자신의 프로젝트에 도입할 수 있는 단일 정보 소스를 구축해야 합니다. 이를 위해서는 개발자 포털과 최신 문서가 필요합니다.

API Connectivity Manager는 F5 NGINX Management Suite의 일부로, API 게시, 버전 관리 및 문서화를 개발 워크플로에 직접 통합할 수 있도록 지원하여 API 개발자 포털을 항상 최신 상태로 유지합니다. API와 관련 문서를 제공하는 API 개발자 포털을 손쉽게 만들 수 있을 뿐만 아니라, API Connectivity Manager를 사용하면 사용자 지정 페이지를 추가하고 브랜드에 맞게 개발자 포털을 완전히 맞춤 설정할 수 있습니다.

API Connectivity Manager가 몇 가지 구체적인 사용 사례를 해결하는 데 어떻게 도움이 되는지 살펴보겠습니다. 자세한 지침은 API Connectivity Manager 설명서에서 개발자 포털 클러스터 설정 및 개발자 포털 게시 항목을 참조하세요.

API 문서 자동 생성

API 사용자가 문서에서 기대하는 품질과 상세 수준은 바쁜 API 개발자가 제한된 시간과 리소스로 현실적으로 제공할 수 있는 수준과 큰 차이가 나는 경우가 많습니다. 자체 개발한 문서화 도구 중 상당수는 개발 수명 주기나 다른 엔지니어링 시스템과 제대로 통합되지 않습니다. 하지만 반드시 그럴 필요는 없습니다.

NGINX의 지원 방식: API Connectivity Manager는 OpenAPI 사양을 사용하여 API를 API 게이트웨이에 게시하고 개발자 포털에서 관련 문서를 자동으로 생성합니다. 이를 통해 API 개발자의 시간을 절약하고 API 사용자가 필요한 정보를 언제든지 찾을 수 있도록 합니다. OpenAPI 사양 파일은 API Connectivity Manager 사용자 인터페이스에서 직접 업로드하거나 REST API를 통해 호출을 전송하여 업로드할 수 있습니다. 따라서 CI/CD 파이프라인을 통해 문서화 프로세스를 손쉽게 자동화할 수 있습니다.

API Connectivity Manager에서 문서를 게시하려면 왼쪽 탐색 열에서 서비스를 클릭하여 서비스 탭을 엽니다. 워크스페이스 이름을 클릭하거나 새 워크스페이스를 만듭니다.

워크스페이스에 들어가면 워크스페이스의 이름과 설명이 표시된 상자(스크린샷의 example-api) 아래에서 API Docs를 클릭합니다. Add API Doc 버튼을 클릭하여 OpenAPI 사양 파일을 업로드합니다. Save 버튼을 클릭하여 개발자 포털에 문서를 게시합니다.

그림 1: OpenAPI 사양 파일을 API Connectivity Manager에 업로드하여
문서 만들기

적절한 버전 관리 보장

버전 변경은 항상 신중하게 처리해야 하며, 여러 서비스가 하나의 API와 상호 작용할 수 있는 마이크로서비스 환경에서는 특히 더 그렇습니다. 새 버전을 도입하고 이전 버전을 폐기할 때 신중하게 접근하지 않으면 단 하나의 호환성을 깨뜨리는 변경으로 인해 수십 개의 마이크로서비스에 연쇄적인 장애가 발생할 수 있습니다.

NGINX의 지원 방식: API Connectivity Manager에서 OpenAPI 사양 파일을 사용하면 API 버전을 손쉽게 관리할 수 있습니다. 버전 번호를 설정할 수 있을 뿐만 아니라 각 버전에 대한 문서를 제공하고 상태(최신, 활성, 사용 종료 또는 지원 중단)를 관리할 수도 있습니다.

새 버전의 API를 게시하려면 왼쪽 탐색 열에서 서비스를 클릭합니다. 표에서 워크스페이스 이름을 클릭한 다음, 열리는 페이지에서 환경 이름을 클릭합니다. 이어서 + 프록시 추가 버튼을 클릭합니다. 여기에서 OpenAPI 사양을 업로드하고 기본 경로와 버전을 설정하여 URI(예: /api/v2/)를 생성한 후 기타 중요한 메타데이터를 입력할 수 있습니다. 게시 버튼을 클릭하여 API 프록시를 저장하고 게시합니다.

API의 원래 버전은 새 버전과 함께 계속 사용할 수 있습니다. 따라서 사용자는 애플리케이션이나 서비스를 최신 버전으로 점진적으로 마이그레이션할 시간을 확보할 수 있습니다. 준비가 완료되면 API의 원래 버전을 완전히 지원 중단할 수 있습니다. 그림 2는 게시되어 프로덕션 환경에서 운영 중인 Sentence Generator API의 두 가지 버전을 보여 줍니다.

그림 2: API Connectivity Manager에서 활성 API 버전 관리

API 자격 증명 생성

API 도입을 촉진하려면 API 소비자의 온보딩 절차를 최대한 간소화해야 합니다. 사용자가 필요한 API를 찾은 후에는 개발자 포털에 안전하게 로그인하여 자격 증명을 생성할 수 있어야 합니다. 이 자격 증명을 통해 사용자는 API 기능에 액세스할 수 있습니다. 대부분의 경우 사용자가 직접 가입할 수 있도록 셀프서비스 워크플로를 구현하는 것이 좋습니다.

NGINX의 지원 방식: API Connectivity Manager는 개발자 포털에서 셀프서비스 API 워크플로를 지원하므로 사용자가 API 액세스에 필요한 리소스 자격 증명을 직접 생성할 수 있습니다. 포털에서 API 키 또는 HTTP 기본 인증을 사용하여 리소스 자격 증명을 관리할 수 있습니다. 또한 개발자 포털에서 SSO(Single Sign-On)를 활성화하여 액세스를 보호하고, 인증된 API 사용자가 리소스 자격 증명을 관리하도록 할 수 있습니다.

개발자 포털에서 SSO를 빠르게 활성화하려면 왼쪽 탐색 열에서 인프라를 클릭합니다. 표에서 워크스페이스 이름을 클릭합니다(그림 3에서는 team-sentence).

그림 3: 인프라 탭의 워크스페이스 목록

Workspace 페이지의 표에서 구성하려는 Environment의 이름을 클릭합니다(그림 4에서는 prod임).

그림 4: 워크스페이스의 환경 목록

개발자 포털 클러스터 섹션에서 작업 중인 개발자 포털의 … 아이콘을 작업 열에서 클릭하고 드롭다운 메뉴에서 고급 구성 편집을 선택합니다. 그림 5에서 유일한 개발자 포털 클러스터는 devportal-cluster입니다.

그림 5: 개발자 포털 클러스터의 Edit Advanced Config 옵션 선택

그런 다음 왼쪽 탐색 열에서 Global Policies를 클릭합니다. OpenID Connect Relying Party 정책이 있는 행의 … 아이콘을 Actions 열에서 클릭하고 드롭다운 메뉴에서 Edit Policy를 선택하여 정책을 구성합니다. 자세한 내용은 API Connectivity Manager 설명서를 참조하세요.

그림 6: SSO(Single Sign-On)를 사용하도록 OpenID Connect 신뢰 당사자 전역 정책 구성

개발자 포털에서 API 사용해 보기

API 전략의 성공 여부를 측정하는 한 가지 방법은 개발자가 API를 사용해 기본 요청을 보내기까지 걸리는 시간을 보여 주는 ‘첫 API 호출까지 걸린 시간’ 지표를 추적하는 것입니다.

명확하고 간결한 문서는 사용자가 API 사용 방법을 기본적으로 이해하는 첫 관문으로서 필수적입니다. 일반적으로 개발자는 API 요청을 테스트하기 전에 API를 애플리케이션에 통합하기 위한 새 코드를 작성해야 합니다. 개발자 포털에서 실제 데이터를 사용해 API와 직접 상호 작용할 수 있는 방법을 제공하면 개발자가 훨씬 더 빠르게 시작할 수 있습니다. 즉, 애플리케이션 코드를 단 한 줄도 작성하지 않고도 첫 번째 API 호출을 실행할 수 있습니다!

NGINX의 지원 방식: API Connectivity Manager 개발자 포털에서 SSO를 활성화하면 API 사용자는 API Explorer를 사용하여 문서 페이지에서 API 호출을 실행해 볼 수 있습니다. API Explorer를 통해 API의 엔드포인트, 매개변수, 응답 및 데이터 모델을 살펴보고 브라우저에서 직접 API 호출을 테스트할 수 있습니다.

그림 7은 API Explorer가 실제로 작동하는 모습, 즉 이 사례에서는 Sentence Generator API를 사용해 보는 과정을 보여 줍니다. 사용자는 적절한 자격 증명을 선택하고 요청을 생성한 다음, API의 실제 데이터가 포함된 응답을 받습니다.

그림 7: 개발자 포털에서 API 테스트

요약

API는 조직에 매우 중요합니다. API를 관리하고 보호하기 위한 첫 단계는 위치와 관계없이 모든 API의 목록을 작성하는 것입니다. 하지만 API 검색은 해결책의 일부일 뿐입니다. API가 무분별하게 확산되는 근본 원인을 해결하려면 API 인벤토리, 문서화 및 버전 관리를 개발 및 엔지니어링 수명 주기에 통합해야 합니다.

Start a 30일 무료 평가판을 시작해 보세요. NGINX Management Suite에는 API Connectivity Manager, API 게이트웨이로 사용할 NGINX Plus와 API 보안을 위한 NGINX App Protect가 포함되어 있습니다.

작성자 소개

Andrew Stiefel

Andrew Stiefel의 다른 블로그 게시물