서비스 지향 아키텍처는 현대 애플리케이션 개발의 중심이다. 우리는 여러 다양한 서비스의 혼합을 기반으로 애플리케이션을 구축함으로써 최신 세대의 플랫폼을 활용해 확장 가능한 서버리스 분산 애플리케이션을 만들 수 있다. 마이크로소프트는 API를 구축하고 제공하기 위한 저수준 툴을 통해 오래전부터 API 우선 설계 및 개발에 앞장서 왔다.

마이크로소프트 API 전략의 핵심은 오픈API(OpenAPI) 설명 언어다. 스웨거(Swagger)를 기반으로 하는 오픈API는 바이너리와 함께 설명을 표준 빌드 아티팩트로 제공해서 자체 설명적 API를 가진 애플리케이션을 쉽게 구축할 수 있게 해준다. 이 API 설명은 유용하다. 비주얼 스튜디오와 같은 툴이 이 설명을 활용해 클라이언트가 HTTP API와 함께 사용할 수 있는 스캐폴딩을 구축할 수 있기 때문이다. 그러나 지원되지 않는 툴 또는 언어로 코드를 빌드하는 경우는 어떨까?

팀즈 SDK의 최신 릴리스에 대한 문서에는 HTTP API 지원을 추가하기 위한 프로젝트 키오타(Project Kiota)라는 오픈소스 툴에 관한 내용이 나온다. 깃허브 리포지토리는 키오타가 오픈API 설명을 다루기 위한 독립형 CLI 기반 툴임을 보여준다. 키오타는 다트, 고, 루비를 포함한 많은 주요 언어를 지원한다. 상태 페이지에 따르면 스위프트와 타입스크립트를 위한 작업도 진행 중이다. 기반 프레임워크 자체가 새로운 언어 지원을 신속하게 추가할 수 있도록 설계됐다.

프로젝트 키오타에 대해 알아보기

마이크로소프트는 이 프로젝트의 목적이 “호출해야 하는 모든 API에서 다른 API 클라이언트 라이브러리에 대한 종속성을 취해야 할 필요성을 없애는 것”이라고 설명한다. 그 의도는 사용하는 각 언어마다 새로운 REST 라이브러리를 배울 필요가 없도록 하는 데 있다. 대신 생성된 메서드와 객체를 사용하면 된다. 키오타는 JSON 페이로드를 직렬화/역직렬화하기 위한 기본 툴 모음을 제공한다.

유용한 부분은 오픈API 설명의 어떤 요소를 구현하고 있는지를 명시해서 생성된 코드를 단순화하고 애플리케이션이 지나치게 복잡해지는 것을 방지할 수 있다는 점이다. 닷넷의 최소 API와 마찬가지로 키오타도 복잡성을 더하는 것이 아니라 개발 워크플로우를 단순화하기 위한 툴이다.

마이크로소프트는 키오타를 쉽게 시작할 수 있도록 해준다. 키오타는 많은 언어, 툴체인과 함께 작동하도록 설계된 만큼 설치하고 사용하는 방법도 공식적인 방법과 비공식적인 방법이 혼재한다. 여기 소개하는 방법으로 되지 않는다 해도, 키오타는 닷넷 애플리케이션이고 깃허브에 소스 코드가 나와 있으므로 직접 컴파일할 수 있다.

개발 툴체인에 키오타 사용하기

첫 번째, 그리고 아마도 가장 많이 사용될 옵션은 그냥 바이너리를 다운로드하는 것이다. 리눅스, 맥OS, 윈도우 버전이 제공된다. 설명서에 리눅스 또는 윈도우용 ARM빌드에 대한 언급은 따로 없지만 깃허브에서 리눅스 ARM 빌드를 다운로드할 수 있다. 윈도우 ARM 사용자는 x64 빌드를 다운로드하고 윈도우 프리즘(Prism) 에뮬레이터를 사용해야 한다.

다른 방법은 사전 빌드된 도커 이미지를 사용하는 것이다. 마이크로소프트는 로컬 오픈API 파일과 온라인에 호스팅된 설명에서 클라이언트 라이브러리를 빌드하기 위한 몇 가지 샘플 명령줄 호출을 제공한다. 윈도우에서 사용하는 경우 WSL2에 도커를 미리 설치하고 리눅스 환경 내에서 컨테이너를 실행해서 원하는 개발 환경으로 출력을 내보내는 것이 좋다.

닷넷 SDK 최신 빌드를 사용 중이라면 닷넷 CLI에서 툴체인에 키오타를 추가할 수 있다. 여기서도 가장 보편적인 각 닷넷 개발 플랫폼을 위한 버전이 있으며, 맞는 버전을 다운로드하려면 적절한 런타임 식별자가 필요하다. 예를 들어 최신 애플 실리콘 맥을 닷넷 개발 플랫폼으로 사용한다면 osx-arm64 식별자를 사용해서 해당 버전을 설치한다.

깃허브 액션에서 키오타를 사용하면 클라이언트 코드 빌드 프로세스를 자동화할 수 있다. 먼저 코드 체크아웃과 관련된 단계를 정의한다. 코드를 체크아웃할 때 마이크로소프트에서 제공하는 키오타 빌드를 사용해 클라이언트를 업데이트하고 로컬 브랜치로 작업한다. 이렇게 하면 항상 코드에서 API의 최신 버전을 사용하도록 보장할 수 있다.

asdf 툴 버전 관리자 또는 홈브루(Homebrew) 맥OS 패키지 관리자와 같은 서비스를 사용하는, 커뮤니티에서 구축한 대안도 있다. 이러한 툴은 자체 리포지토리를 사용하지만 툴체인 패키지 관리를 위해 이와 같은 툴을 선택한다면 개발자 또는 개발팀에서 개발 디바이스를 신속하게 리프레시하고 업데이트할 수 있도록 키오타를 설치 스크립트에 빠르게 추가할 수 있다.

비주얼 스튜디오 코드 사용자는 키오타를 편집기에 직접 연결하는 프리뷰 확장 기능을 활용할 수 있다. 비주얼 스튜디오의 REST API 클라이언트 코드 생성기에 사용되는 툴(필요시 키오타를 설치함)과는 다른 툴이지만, 이는 마이크로소프트의 두 가지 주요 개발 툴 모두 키오타의 기능을 활용할 수 있음을 의미한다.

키오타로 관리되는 API를 사용해 작업하기

키오타 사용 방법은 비교적 간단하다. 닷넷을 사용한다면 먼저 키오타 명령줄 툴을 설치하고, 프로젝트의 설정이 대상 프레임워크와 언어 버전에 맞는지 확인한다. 현대 닷넷 애플리케이션은 닷넷 6 이상이어야 한다(적절한 버전의 닷넷 스탠다드와 함께 이전 버전을 사용할 수도 있음). 각 언어에는 이와 비슷한 요구사항이 있다. C#의 경우 버전 7.3 이상이어야 한다.

코드에 키오타의 종속 항목을 포함해야 하는데 종속 항목은 번들을 사용해 설치할 수 있다. 마이크로소프트는 지원되는 언어와 직렬화 옵션, HTTP 구현에 필요한 추상화와 패키지에 대해 세부적인 정보를 제공한다. 인증된 API를 사용하는 경우 다양한 ID 관리 툴에 대한 지원을 포함해야 한다. 번들을 사용하면 작업이 상당히 간소화되지만 파이썬, PHP와 같이 필요에 따라 종속성 지원을 추가해야 하는 언어도 있다.

이제 오픈API YAML에서 API 클라이언트를 생성할 수 있다. 이는 로컬 파일(대부분 자체적인 오픈API 설명을 작성하는 경우에 해당)일 수도 있고, 공개 API를 위한 URL일 수도 있다. 클라이언트 클래스는 명령줄 툴을 사용해 생성되며 대상 언어와 클라이언트 클래스 이름, 네임스페이스, 오픈API YAML의 위치, 그리고 마지막으로 출력 디렉터리를 정의한다. 다른 옵션을 사용해 출력을 조정할 수 있다. 예를 들어 키오타의 최신 버전만 빌드하거나 하위 호환성을 낮춰 크기를 줄일 수 있다.

키오타가 API를 다루는 데 필요한 코드를 빌드하면 개발자는 애플리케이션에 이 코드를 포함할 수 있다. 생성된 네임스페이스를 가져오고 연결을 승인하고 키오타에서 생성한 클래스를 기반으로 클라이언트 객체를 생성해야 한다. 이러한 작업은 모두 매우 간단하다. API에 대한 호출은 키오타에서 생성한 클래스의 메서드에 캡슐화되며, 표준 HTTP 동작을 지원하므로 API에서 데이터를 가져오고 게시할 수 있다.

언어 선택

파이썬과 같은 다른 언어를 사용하는 경우에도 프로세스는 비슷하다. 단지 파이썬의 경우 필수 요소 및 종속 항목 번들이 없으므로 pip를 사용해서 적절한 키오타 라이브러리를 설치해야 한다. 키오타 클라이언트를 빌드하고 사용하는 과정은 많은 부분에서 닷넷과 동일하다. 필요에 따라 클래스를 가져와 비동기적으로 사용한다.

키오타 경험은 키오타를 지원하는 모든 언어에서 동일하다. 먼저 프로젝트에 종속 항목을 로드하고 오픈API 정의에서 클라이언트를 빌드한 다음 생성된 클라이언트 클래스를 가져와 사용한다. 일단 가져오기를 정의한 다음에는 호출하는 API의 업데이트된 버전이 나올 때까지는 애플리케이션 코드에 영향을 주지 않고 클라이언트를 리프레시할 수 있다.

그렇다면 키오타를 사용할 이유는 무엇일까? 오픈API의 오랜 약속은 공통 API 설명 언어를 사용하면 개발자가 클라이언트 빌드 프로세스를 자동화할 수 있다는 것이었다. 키오타는 대부분의 일반적인 개발 툴체인에서 작동하는 언어 중립적 아키텍처를 통해 이 약속을 확실히 이행한다. 키오타는 표준 클래스 모음을 제공함으로써 학습의 어려움을 최소화한다. 무엇이 출력되고 이를 코드에서 어떻게 사용할지를 알 수 있다.

용도는 코딩 워크플로우에 국한되지 않는다. 키오타는 서비스 지향 아키텍처를 위한 테스트를 신속하게 구축하고 CI/CD 파이프라인에 적용해서 서비스가 올바르게 구축되고 용도에 적합한지 확인할 수 있다. 마찬가지로, 로우 코드 환경의 일부로 키오타를 사용해서 워크플로우에서 즉시 사용 가능한 커넥터를 만들고 검증할 수 있다.

위에서 마지막 옵션은 에이전트 AI와 잘 맞는다. AI 쿼리에서 서비스가 실행될 때마다 새 API 호출을 생성하는 대신, 키오타 클라이언트가 일종의 의미 기억(semantic memory)에 상응하는 API 역할을 해서 API 구조를 포착하고 이후 작업에서 AI가 사용할 수 있도록 클라이언트 라이브러리를 제공할 수 있다. 에이전트에 API 기억을 제공하면 위험을 낮추고 서비스에 대한 호출을 관리 및 보호해서 일관된 결과를 유지하는 데 도움이 된다.
dl-itworldkorea@foundryco.com