API 개발자 포털 이 필요한 이유

API의 수가 계속 증가함에 따라 API 포트폴리오 관리의 복잡성도 증가하고 있습니다. 어떤 API를 사용할 수 있는지, 어디에 있는지 검색하고 추적하는 것은 물론 사용 방법에 대한 설명서를 찾는 것도 점점 더 어려워지고 있습니다. 전체적인 API 전략을 수집하지 않으면 플랫폼 운영팀이 관리할 수 있는 것보다 더 빠르게 API가 확산될 수 있습니다. 우리는 이 문제를 API Sprawl 이라고 부르며, 이전 포스트에서 이 문제가 왜 그렇게 심각한 위협인지 설명했습니다. 이번 포스팅에서는 NGINX 의 도움을 받아 API 개발자 포털 을 설정하여 API sprawl을 방지할 수 있는 방법을 자세히 살펴봅니다.

비즈니스 라인 전반에서 애플리케이션과 게이터를 연결하고, 파트너와 통합하고, 고객 경험을 제공하기 위해 API에 의존하는 기업이 점점 더 많아지고 있습니다.

목차

1. API 인벤토리 구축
2. API 개발자 포털 로 API 검색 간소화
3. NGINX로 API를 위한 단일 데이터 소스 만들기
3-1. API 문서 자동 생성
3-2. 적절한 버전 관리 보장
3-3. API 자격 증명 생성
3-4. API 개발자 포털에서 API 사용해보기
4. API 개발자 포털 요약

1. API 인벤토리 구축

궁극적으로 API는 사용되기 전까지는 유용할 수 없으며, 이는 API 소비자들이 API를 찾을 수 있는 방법이 필요하다는 것을 의미합니다. 적절한 시스템이 갖춰져 있지 않으면 API가 무분별하게 확산되어 개발자가 애플리케이션에 필요한 API를 찾기가 어렵습니다. 기껏해야 여러 비즈니스 라인에서 API 목록을 보관하고 비공식적인 엔지니어 네트워크를 통해 팀 간에 지식을 공유하는 정도입니다.

API sprawl 문제를 해결하기 위한 첫 번째 단계 중 하나는 API에 대한 단일 소스를 만드는 것입니다. 이 프로세스는 API 인벤토리를 구축하는 것으로 시작됩니다. 하지만 정확한 인벤토리 구축은 새로운 API가 도입되고 오래된 API가 사용 중단됨에 따라 끊임없이 변화하는 목표이기 때문에 쉽지 않은 과제입니다. 또한 시간이 지나면서 잊혀졌거나, 부적절하게 사용 중단되었거나, 표준 프로세스 외부에 구축된 API 등 환경 전반에서 “shadows APIs”를 찾아야 합니다.

관리되지 않는 API는 API sprawl의 가장 교활한 증상 중 하나로, 명백한 보안 영향과 숨겨진 비용을 모두 초래합니다. 사용 가능한 API에 대한 정확한 인벤토리가 없으면 API팀은 문서를 찾는 데 시간을 소비해야 합니다. 여러 팀이 유사한 기능을 구축하기 때문에 중복된 노력이 낭비될 위험이 큽니다. 또한 적절한 버전 관리 없이 특정 API를 변경하면 비용이 많이 드는 재작업이 연쇄적으로 발생하거나 심지어 중단될 수도 있습니다.

자동화된 API 검색과 같은 기술은 관리되지 않는 API의 증상을 식별하고 처리하는 데 도움이 될 수 있습니다. 하지만 문제를 해결하여면 근본적인 원인, 즉 깨진 프로세스와 소유권 부족을 제거해야 합니다. 실제로 API 인벤토리와 문서를 CI/CD 파이프라인에 통합하는 것이 장기적으로 API 포트폴리오 전반에 대한 가시성을 보장하는 유일한 접근 방식입니다. 온라인 상태가 될 때마다 모든 API를 수동으로 추적할 필요 없이 예외만 식별하고 수정하면 됩니다.

2. 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 게시, 버전 관리 및 문서화를 원활하게 통합하는 자동화된 low-touch 접근 방식이 필요합니다.

3. NGINX로 API를 위한 단일 데이터 소스 만들기

원활한 API 검색을 지원하려면 개발자가 API를 찾고, 사용 방법을 배우고, 프로젝트에 온보딩할 수 있는 단일 소스를 만들어야 합니다. 즉, 개발자 포털과 최신 문서가 필요합니다.

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

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

3-1. API 문서 자동 생성

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

NGINX 의 지원 방법: API Connectivity Manager는 OpenAPI 사양을 사용하여 API를 API Gateway에 게시하고 개발자 포털에 관련 문서를 자동으로 생성하여 API 개발자의 시간을 절약하고 API 소비자가 항상 필요한 것을 찾을 수 있도록 합니다. API Connectivity Manager 사용자 인터페이스를 통해 직접 또는 REST API를 통해 호출을 전송하여 Open API 사양 파일을 업로드할 수 있습니다. 이를 통해 CI/CD 파이프라인을 통해 문서화 프로세스를 쉽게 자동화할 수 있습니다.

API 연결 관리자에서 문서를 게시하려면 왼쪽 탐색 열에서 Services를 클릭하여 Services 탭을 엽니다. 워크스페이스의 이름을 클릭하거나 새 워크스페이스를 만듭니다.

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

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

3-2. 적절한 버전 관리 보장

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

NGINX 의 지원 방법: API Connectivity Manager와 함께 OpenAPI 사양 파일을 사용하면 API의 버전을 쉽게 제어할 수 있습니다. 버전 번호를 설정하는 것 외에도 각 버전에 대한 문서를 제공하고 해당 상태(latest, active, retired, or deprecated)를 관리할 수 있습니다.

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

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

그림 2: API 연결 관리자 내에서 활성 API 버전 관리하기

3-3. API 자격 증명 생성

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

NGINX 의 지원 방법: API Connectivity Manager는 개발자 포털에서 자체 관리형 API 워크플로를 지원하므로 사용자가 API에 액세스하기 위한 자체 리소스 자격 증명을 생성할 수 있습니다. 리소스 자격 증명은 API keys 또는 HTTP 기본 인증을 사용하여 포털에서 관리할 수 있습니다. 또한 개발자 포털에서 single-sign-on(SSO)을 활성화하여 액세스를 보호하고 인증된 API 소비자가 리소스 자격 증명을 관리할 수 있도록 할 수도 있습니다.

개발자 포털에서 SSO를 빠르게 사용 설정하려면 왼쪽 탐색 열에서 Infrastructure를 클릭합니다. 표에서 워크스페이스의 이름을 클릭합니다(그림 3에서는 team-sentence).

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

워크스페이스 페이지의 표에서 구성하려는 환경의 이름을 클릭합니다(그림 4에서는 prod).

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

Developer Portal Clusters 섹션에서 작업 중인 개발자 포털의 Actions 열에 있는 … 아이콘을 클릭하고 드롭다운 메뉴에서 Edit Advanced Config 를 선택합니다. 그림 5에서 단일 개발자 포털 클러스터는 devportal-cluster입니다.

그림 5: 개발자 포털 클러스터의 고급 구성 편집 옵션 선택하기

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

그림 6: 싱글 사인온을 사용하도록 Connect Relaying Party 글로벌 정책 구성

3-4. API 개발자 포털 에서 API 사용해보기

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

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

NGINX 의 지원 방법: API Connectivity Manager 개발자 포털에 SSO를 활성화하면 API 소비자는 API 탐색기를 사용하여 문서 페이지에서 API 호출을 시도해 볼 수 있습니다. API 탐색기를 사용하여 API의 엔드포인트, 매개변수, 응답, 데이터 모델을 탐색하고 브라우저에서 직접 API 호출을 테스트할 수 있습니다.

그림 7은 API 탐색기가 실제로 작동하는 모습을 보여줍니다. 이 예에서는 문장 생성기 API를 사용해 봅니다. 사용자는 적절한 자격 증명을 선택하고 요청을 생성한 후 API로부터 실제 데이터가 포함된 응답을 받습니다.

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

4. API 개발자 포털 요약

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

NGINX Plus를 직접 사용해 보시려면 30일 무료 평가판을 신청하거나 NGINX STORE에 연락하여 문의하십시오.

NGINX에 대한 최신 정보들을 빠르게 전달받고 싶으시다면, 아래의 뉴스레터를 구독하세요.