새로운 API 사용 방법을 배우는 초기 단계와 주의할 점

새로운 시스템 API를 배우는 것은 어려운 과제처럼 느껴질 수 있습니다. 네트워크 엔지니어로서 시작하는 방법에 대해 불확실한 느낌을 가질 수도 있습니다. 다행히도, controller 제품, 클라우드 시스템, 또는 API 디바이스와 같은 API 기반 시스템을 배우는 방법은 동일한 일련의 단계를 따릅니다. 이 글에서는 새로운 API 사용 방법을 배울 때 초기 단계를 안내하고, 문서, 클라이언트 라이브러리, 그리고 API 인증에 주목해야 할 중요한 측면을 강조합니다. 상용 제품과 오픈 소스 프로젝트를 사용할 수 있으며, 편의상 여기서는 제품이라는 용어로 통일합니다. 해당 포스트에서는 문서, 클라이언트 라이브러리 그리고 API 인증에 초점을 맞추고 있습니다.

목차

1. 정리
2. API 클라이언트 라이브러리
3. 입증
4. API 결론

1. 정리

첫 번째 단계는 API 문서를 찾는 것이며, 거기서 찾아야 할 첫 번째 항목은 “Quick Start”입니다. Quick Start는 API와 처음 상호작용하는 데 필요한 최소한의 단계를 지정하는 형태의 문서입니다. 사실상 이는 실제로 유용한 작업을 수행하지 않더라도 API와 성공적으로 상호작용할 수 있는지 확인하는 “Hello, world” 프로그램과 같은 역할을 합니다.

일반적으로, 문서에서 버전별 정보를 주시하는 것이 중요합니다. 일부 예제는 API의 기능에 의존할 수 있지만 현재 사용 중인 버전에서 지원되지 않을 수 있습니다.

문서는 일반적으로 다음 세 가지 형태 중 하나로 제공됩니다.

  • 제품에 내장 – 대부분의 현대 제품은 API 문서를 제품에 내장하고 OpenAPI 사양 또는 Swagger 사양으로 자동 생성합니다. 제품이 이러한 방식으로 API 문서를 제공하는 경우, 웹 브라우저 인터페이스를 사용하여 API 기능을 직접 시도해 볼 수 있습니다. 제품을 평가하는 과정에서 이러한 문서를 제공한다면 대개 데모 시스템에 접근하여 API 기능을 상호작용적으로 탐색할 수 있습니다.

    내장된 방식의 장점은 API 문서가 코드로부터 자동으로 생성되므로 현재 사용 중인 제품 버전과 일치한다는 것입니다. 그러나 개발자들이 코드에 얼마나 자세한 주석을 달았느냐에 따라 문서가 부족하고 도움이 되지 않을 수도 있습니다.

    제품이 OpenAPI 사양 파일을 다운로드로 제공한다면 (일반적으로 JSON 또는 YAML 형식으로), 해당 파일을 다른 OpenAPI 도구와 함께 사용할 수 있습니다. 이러한 도구에는 언어별 클라이언트 생성기 (클라이언트 라이브러리 참조)와 같은 것들이 포함됩니다.
  • 웹 사이트의 interactive 웹 페이지 – 일부 제품은 웹 사이트에서 문서를 제공하며, 로그인 페이지 뒤에 숨겨져 있거나 공개적으로 접근 가능합니다. 이 방식의 장점은 문서가 일반적으로 버전별로 검색 가능하다는 것입니다. 좋은 문서에는 버전별 노트가 포함되어 있으며, 예를 들어 새로운 기능이 추가되거나 사용이 중단되었을 때 설명되어 있습니다. 업그레이드를 계획할 때는 다른 소프트웨어 업그레이드와 마찬가지로 릴리스 노트(README, CHANGELOG 등)를 확인하십시오.
  • 정적 문서 – 이에는 PDF, README, Wiki 등이 포함됩니다. 불행히도, 이러한 형태의 문서는 종종 최신 정보가 누락되거나 불완전합니다. 이는 제품 개발팀이 별도의 워크플로우를 도입하여 자체 도구 (워드 프로세서, 출판 시스템 등)를 사용해야 하기 때문입니다. 이러한 형태의 문서를 제공받은 경우, 제품 API 전문가들과 함께 시간을 요청하여 이 문서들의 품질과 유지 보수에 대한 평가를 받아볼 수 있습니다.

2. API 클라이언트 라이브러리

클라이언트 라이브러리는 API와 상호작용하는 것을 더 쉽게 만들기 위한 소프트웨어입니다. 클라이언트 라이브러리는 프로그램에 통합되므로 언어별로 제공되며, 예를 들어 공급업체는 Python으로 된 클라이언트 라이브러리를 제공하지만 Luby나 Perl로 된 것은 제공하지 않을 수 있습니다. 일부 클라이언트 라이브러리는 제품과 공식적으로 관련되지 않을 수도 있으며, 개발팀의 커뮤니티 노력의 일환으로 느슨하게 연관될 수 있습니다. 커뮤니티 지원 클라이언트 라이브러리는 일반적으로 최선의 노력으로 제공되며, 공급업체가 공식적으로 지원하지는 않습니다.

이상적으로는 공급업체가 제공하는 클라이언트 라이브러리를 사용하는 것이 좋습니다. 이렇게 하면 공급업체가 제품 변경에 맞춰 라이브러리를 최신 상태로 유지하고 지원(무료 또는 유료)을 제공할 것으로 기대할 수 있습니다. 대부분의 경우 클라이언트 라이브러리는 오픈 소스이며 GitHub와 같은 저장소에서 공개적으로 사용 가능합니다. 해당 저장소의 이슈 목록을 검토하여 알려진 문제, 기능 요청 및 질문을 살펴보는 것이 시간을 들여야 할 부분입니다. 이는 라이브러리의 품질과 유지보수자들이 사용자들과 얼마나 잘 상호작용하는지를 파악하는 데 도움이 될 수 있습니다.

만약 제품이 다운로드용 OpenAPI 사양을 제공한다면, openapi-generator와 같은 소프트웨어를 사용하여 원하는 언어를 기반으로 클라이언트를 생성할 수도 있습니다. 클라이언트 생성기를 사용하는 것에는 장단점이 있지만, API를 처음 시작할 때 코드 생성기는 API 작동 방식을 빠르게 확인할 수 있는 좋은 방법입니다.

클라이언트 라이브러리 대안으로, 공급업체가 Postman 컬렉션을 제공할 수도 있습니다. Postman은 무료 API 개발 도구입니다. Postman 컬렉션은 Postman의 point-and-click 사용자 인터페이스를 통해 사용할 수 있는 API 호출의 패키지화된 집합입니다. 공급업체들은 종종 Postman 컬렉션을 문서나 API 소프트웨어 개발 키트(SDK)의 일부로 제공하여 코드를 작성하지 않고도 API와 상호작용할 수 있도록 합니다. 컬렉션은 주로 소프트웨어를 직접 프로그래밍 언어로 코드 스니펫을 생성할 수 있으므로, 빠르게 자체 클라이언트 라이브러리를 만드는 효과적인 방법으로 활용할 수도 있습니다.

3. 입증

API 인증에는 두 가지 일반적인 방법이 있습니다. 로그인 자격 증명과 토큰. 로그인 자격 증명을 사용하는 경우, 다른 방식으로 제품에 접근할 때와 마찬가지로 동일한 사용자 이름과 비밀번호를 사용합니다 (예: 브라우저에서). 네트워크 디바이스 API를 사용하는 경우, 일반적으로 이 방법을 사용하게 됩니다. 왜냐하면 로그인 자격 증명은 일반적으로 인증, 권한 부여 및 계정 관리 (AAA) 시스템과 연결되어 디바이스 인증과 명령 승인을 수행하기 때문입니다.

비교적 토큰은 임의의 문자열로 나타납니다. 일부 API는 API를 사용하기 전에 로그인 자격 증명을 기반으로 토큰을 생성하도록 요구하여 인증을 두 단계로 수행합니다. 다른 일부 API는 공급업체가 설정한 시스템을 사용하여 먼저 토큰을 생성하도록 허용하거나 필수로 요구하며, 토큰을 한 번 노출시킨 후에는 다시 토큰을 표시하지 않습니다. 이 경우에는 토큰을 안전한 장소에 보관해두어 나중에 사용해야 합니다. 많은 API는 RFC 7519에서 정의된 JSON Web Token이라는 industry-token 시스템을 사용합니다.

또 다른 주의할 점은 토큰이 만료되는 시간이 있을 수 있다는 것입니다. 따라서 현재 사용 중인 토큰이 만료되기 전에 새로운 토큰을 생성해야 하며, 그렇지 않으면 잠금 상태에 놓일 수 있습니다. 예를 들어, 어떤 API에서는 로그인 자격 증명을 기반으로 유효 기간이 1시간인 토큰을 생성하도록 요구할 수 있습니다. 프로그램이 1시간보다 더 오래 실행될 가능성이 있는 경우 토큰을 갱신하는 기능을 구현해야 합니다. 일부 시스템에서는 새로운 토큰을 얻기 위해 프로그램이 로그인 자격 증명을 다시 제공해야 할 수도 있지만, 다른 시스템에서는 로그인 자격 증명을 다시 요구하지 않고도 토큰을 갱신하는 메커니즘을 갖추고 있을 수 있습니다.

가끔 자격 증명은 API 요청의 일부로 배포되며, 가장 흔히 HTTP Authorization 요청 헤더에 포함됩니다. 그러나 일반적인 해결책이 없으며, 시스템이 Auth 2.0, OpenID Connect, SAML2와 같은 인증 프로토콜을 사용하는지 여부에 따라 메커니즘이 복잡해질 수 있습니다. 클라이언트 라이브러리를 사용할 수 있다면 일반적으로 권장되는 방법입니다. 이는 보통 인증 프로세스의 복잡성을 감추고, 개발자가 단순히 로그인 자격 증명 또는 토큰을 제공하기만 하면 됩니다.

4. API 결론

새로운 API를 배우기 시작할 때는 먼저 해당 API의 문서를 찾고, 빠른 시작(quick-start) 프로세스를 실행하여 API와 상호작용이 가능한지 확인하는 것으로 시작하세요. 만약 공급업체(vendor)가 클라이언트 라이브러리 패키지를 제공한다면, 먼저 그것을 사용해보세요. 필요에 완벽하게 부합하지 않더라도, 해당 클라이언트 라이브러리를 통해 API의 동작 방식을 익히고, 코드를 살펴봄으로써 그 뒤에 숨겨진 메커니즘을 이해할 수 있습니다. 이러한 지식을 바탕으로 자체 클라이언트 라이브러리를 개발할지 아니면 기존 라이브러리를 수정할지 결정할 수 있습니다.

또한 AAA(인증, 권한, 계정) 메커니즘을 이해해야 합니다. API가 인증 정보를 인코딩하는 방식에 따라 프로그램의 구조에 영향을 미칠 수 있으며, 특히 프로그램이 일반적인 토큰 유효 기간보다 길게 실행되는 경우에는 더욱 중요합니다. 가능한 경우 항상 Postman 컬렉션을 활용하세요. 이러한 컬렉션은 코드를 작성하지 않아도 API를 검증할 수 있는 독립적인 메커니즘이며, API의 동작을 배우고, 코드 스니펫을 생성하여 프로그램에 통합할 수 있습니다.

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

아래 뉴스레터를 구독하고 NGINX의 최신 정보들을 빠르게 전달받아보세요.