API Discovery를 위한 API 개발자 포털이 필요한 이유

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

API의 수가 계속 증가함에 따라 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 검색과 같은 기술을 사용하면 관리되지 않는 API의 증상을 식별하고 처리하는 데 도움이 될 수 있습니다. 하지만 문제를 해결하려면 근본 원인인 망가진 프로세스와 소유권 부족을 제거해야 합니다. 실제로, API 인벤토리와 문서를 CI/CD 파이프라인에 통합하는 것은 장기적으로 API 포트폴리오 전반의 가시성을 보장하는 유일한 방법입니다. 온라인에 올라오는 모든 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를 찾고, 사용 방법을 배우고, 프로젝트에 온보딩할 수 있는 단일 출처를 만들어야 합니다. 즉, 개발자 포털과 최신 문서가 필요하다는 뜻입니다.

F5 NGINX Management Suite의 일부인 API Connectivity Manager를 사용하면 API의 게시, 버전 관리 및 문서화를 개발 워크플로에 직접 통합할 수 있으므로 API 개발자 포털이 항상 최신 상태가 유지됩니다. API Connectivity Manager를 사용하면 API와 문서를 호스팅하는 API 개발자 포털을 쉽게 만들 수 있을 뿐만 아니라 사용자 정의 페이지를 추가하고 브랜딩에 맞게 개발자 포털을 완벽하게 사용자 정의할 수 있습니다.

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

API 문서를 자동으로 생성

API 사용자가 문서에서 기대하는 품질 및 세부 정보 수준과 바쁜 API 개발자가 제한된 시간과 리소스로 현실적으로 제공할 수 있는 수준 사이에는 종종 큰 차이가 있습니다. 많은 자체 문서화 도구는 개발 라이프사이클이나 다른 엔지니어링 시스템과 통합되지 못합니다. 반드시 그럴 필요는 없습니다.

NGINX가 어떻게 도움이 될 수 있나요: API Connectivity Manager는 OpenAPI 사양을 사용하여 API 게이트웨이에 API를 게시하고 개발자 포털에 관련 문서를 자동으로 생성하여 API 개발자의 시간을 절약하고 API 소비자가 항상 필요한 정보를 찾을 수 있도록 보장합니다. API Connectivity Manager 사용자 인터페이스를 통해 OpenAPI 사양 파일을 직접 업로드하거나 REST API를 통해 호출을 보낼 수 있습니다. 이를 통해 CI/CD 파이프라인을 통해 문서화 프로세스를 쉽게 자동화할 수 있습니다.

API Connectivity Manager에서 문서를 게시하려면 왼쪽 탐색 열에서 서비스를 클릭하여 서비스 탭을 엽니다. 작업 공간 이름을 클릭하거나 새 작업 공간을 만드세요 .

작업 공간에 들어가면 작업 공간의 이름과 설명이 있는 상자 아래에 있는 API 문서를 클릭합니다(스크린샷에서는 example-api ). API 문서 추가 버튼을 클릭하여 OpenAPI 사양 파일을 업로드하세요. 개발자 포털에 문서를 게시하려면 '저장' 버튼을 클릭하세요.

적절한 버전 관리 보장

버전 변경은 항상 신중하게 처리해야 하며, 이는 특히 여러 서비스가 단일 API와 상호 작용할 수 있는 마이크로서비스 환경에서 더욱 그렇습니다. 새 버전을 도입하고 이전 버전을 폐기하는 데 신중한 접근 방식이 없다면, 단일 중단 변경으로 인해 수십 개의 마이크로서비스에 걸쳐 연쇄적인 중단이 발생할 수 있습니다.

NGINX가 어떻게 도움이 될 수 있나요: API Connectivity Manager와 함께 OpenAPI 사양 파일을 사용하면 API의 버전을 쉽게 제어할 수 있습니다. 버전 번호를 설정하는 것 외에도 각 버전에 대한 문서를 제공하고 버전 상태(최신, 활성, 중단, 더 이상 사용되지 않음)를 관리할 수 있습니다.

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

API의 원래 버전은 새 버전과 함께 계속 사용할 수 있습니다. 이를 통해 사용자는 점진적으로 애플리케이션이나 서비스를 최신 버전으로 마이그레이션할 시간을 얻을 수 있습니다. 준비가 되면 API의 원래 버전을 완전히 사용하지 않도록 설정할 수 있습니다. 그림 2는 게시된 버전과 프로덕션 중인 두 가지 버전의 Sentence Generator API를 보여줍니다.

API 자격 증명 생성

API 채택을 촉진하려면 API 소비자를 위해 온보딩 프로세스를 최대한 간소화해야 합니다. 사용자가 API를 찾으면 개발자 포털에 안전하게 로그인하고 자격 증명을 생성할 수 있는 방법이 필요합니다. 이러한 자격 증명은 사용자에게 API 기능에 대한 액세스 권한을 부여합니다. 대부분의 경우 사용자가 스스로 가입할 수 있도록 자체 관리 워크플로를 구현하고 싶을 것입니다.

NGINX가 어떻게 도움이 될 수 있나요: API Connectivity Manager는 개발자 포털에서 자체 관리형 API 워크플로를 지원하므로 사용자는 API에 액세스하기 위한 자체 리소스 자격 증명을 생성할 수 있습니다. 리소스 자격 증명은 API 키나 HTTP 기본 인증을 사용하여 포털에서 관리할 수 있습니다. 개발자 포털에서 SSO(Single Sign‑On)를 활성화하여 액세스를 보호하고 인증된 API 소비자가 리소스 자격 증명을 관리하도록 할 수도 있습니다.

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

작업 공간 페이지의 표에서 구성하려는 환경의 이름을 클릭합니다(그림 4에서는 prod 입니다).

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

다음으로, 왼쪽 탐색 열에서 글로벌 정책을 클릭합니다. 행의 작업 열에 있는 … 아이콘을 클릭하고 드롭다운 메뉴에서 정책 편집을 선택하여 OpenID Connect 신뢰 당사자 정책을 구성합니다. 자세한 내용은 API 연결 관리자 설명서를 참조하세요.

개발자 포털에서 API를 사용해 보세요

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에서 실제 데이터가 포함된 응답을 받습니다.

요약

API는 귀하의 조직에 매우 중요합니다. API를 관리하고 보호하기 위한 첫 번째 단계는 위치에 관계없이 모든 API를 인벤토리로 작성하는 것부터 시작됩니다. 하지만 API 검색은 솔루션의 일부일 뿐입니다. API 확산의 근본 원인을 해결하려면 개발 및 엔지니어링 라이프사이클에 API 인벤토리, 문서 및 버전 관리를 구축해야 합니다.

API Connectivity Manager , API 게이트웨이인 NGINX Plus , API를 보호하기 위한 NGINX App Protect 등이 포함된 NGINX Management Suite의 30일 무료 평가판을 시작하세요.