마이크로소프트의 API 설계 언어 ‘캐들’ 살펴보기

애저는 마이크로소프트 기술을 이용하면서 규모 있는 작업을 할 때 유용하다. 규모가 큰 프로젝트에서 자체적으로 문제를 일찍 발견하고 해결까지 해주기 때문이다. 과거에는 그런 역할이 하는 솔루션이 비주얼 스튜디오에 지원되려면 몇 년은 기다려야 했지만 이제 상황이 달라졌다. 마이크로소프트의 오픈소스 친화 정책으로 기술 방향은 물론 소스코드까지 깃허브에 공개되면서, 애저와 관련한 다양한 기술이 빠르게 나오고 있는 것이다. 캐들(Cadl)이 그런 의미에서 나온 기술이다. 
 

애저 이용 과정에서 한 가지 문제가 있다면, API를 설계하고 애저의 모든 API를 일관되게 만들 방법을 찾기 쉽지 않다는 점이다. 요즘 방식의 API 정의는 오픈API를 활용해 작성한 것조차 복잡하고 길다. 동일한 접근방식 및 가이드라인을 사용해도 API 정의는 팀마다 강조하는 요소가 다르고, 비슷한 함수를 다루는 방식도 각양각색이다. 이런 부분 때문에 애저의 API 정의 코드 분량은 수천 줄에 달하는 것도 있다.

애저는 API 표면을 최소한 하루 한 번 재컴파일하므로, API의 일관성 확인과 설명 작성 및 테스트의 자동화 가능 여부를 확인 확인해야 한다. 그뿐만 아니라, 특정 종류의 API에 익숙한 개발자가 애플리케이션에 서비스를 추가할 때 완전히 새로운 기법을 배울 필요가 없도록 해야 한다.

오픈API 도구를 사용하는 애플리케이션에 API 정의가 결합되고, 적절한 엔드포인트를 생성하는 환경에서 일관적이지 않은 API 정의는 문제가 될 수 있다. 거기다 API가 진화하면서 HTTP 접근 이상을 요구함에 따라 REST를 넘어 그래프QL과 gRPC로 이동해야 할 때는 더 큰 문제가 된다.
 

간결한 API 언어, 캐들 톺아보기

마이크로소프트는 API 개발의 많은 부분을 캐들이라는 언어로 옮기기 시작했다. 캐들은 API 구조를 프로그램에 따라 먼저 정의한 후, 오픈API 정의로 컴파일하는 데 도움이 된다. API 정의를 반복적으로 제공할 때 사용하기 위해 개발됐다. 정의로부터 설계를 추상화하는 캐들의 결과물은 훨씬 더 간결하므로 비주얼 스튜디오와 같은 플랫폼에서 오픈API 도구의 구문 분석이 빠르고 효율적이다.

조금 더 자세하게 살펴보자. 캐들은 언뜻 보면 닷넷 언어와 유사점이 있는 자바스크립트 같은 언어다. 마이크로소프트는 캐들을 ‘API를 위한 타입스크립트(TypeScript)’라고 묘사한다. 다시 말해 C#에 익숙한 사람이 사용하기 쉽게 만든 것이다. 마이크로소프트가 만든 다른 언어와 마찬가지로 캐들은 마이크로소프트의 자체 개발 도구와 잘 호환된다. 따라서 비주얼 스튜디오 및 비주얼 스튜디오 코드의 언어 서버에 캐들 확장 프로그램을 추가하여 내장 구문 강조, 코드 완성, 린팅(linting) 등의 지원을 받을 수도 있다.

마이크로소프트가 굳이 캐들이라는 언어를 따로 만든 것은 좋은 선택이다. 캐들을 통해 아키텍처 제약 조건을 일종의 원칙으로 만들고 라이브러리에서 공통 구조를 적용할 수 있다. API 설명은 아키텍처 규칙의 한계를 벗어날 경우, 컴파일되지 않으므로 해당 원칙은 캐들 환경에 의해 반드시 실행된다. API 설계자들은 아키텍처 팀이 정한 지침 내에서 작업해야 한다. 이 과정을 캐들 설계자들은 산출물 ’자동 오류 제거(CBC)’라고 표현한다.

캐들은 오픈소스로 깃허브에 공개된다. 문서화까지 꽤 잘 돼 있다. 오픈API와 스웨거(Swagger) 형식 산출물 둘 다와 비교해 보는 등 캐들 코드로 실험할 수 있는 테스트 전용 사이트(playground)도 따로 제공된다. 캐들 코드를 보면 오픈API 산출물에 비해 훨씬 더 간결하다는 사실을 금방 알 수 있을 것이다. 34줄짜리 캐들 API 설명은 오픈 API로 바꾸면 분량이 359줄이 된다. 10배 더 길어지는 셈이다. 캐들 코드는 기술이 적절히 그룹화된 상태로 하나의 화면에 다 들어가기 때문에 관리하기도 훨씬 더 수월하다.
 

캐들로 API 정의하기

캐들 설치는 간단하다. 컴파일러와 CLI는 npm에 호스팅 된 동일한 애플리케이션의 일부다. 일단 다운로드하여 설치한 후에는 CLI를 사용하여 함께 들어있던 비주얼 스튜디오 및 비주얼 스튜디오 코드 확장 프로그램을 설치할 수 있다. 프로그램을 설치했다면 바로 API 정의를 구축할 수 있다. 캐들 CLI로 프로젝트를 초기화하면, 간단한 일련의 프롬프트를 거쳐 기본 템플릿 선택, 이름 추가, 기본 라이브러리 선택 등을 할 수 있다. 빠른 컴파일을 통해 모든 것이 제자리에 있고 작동할 준비가 되었는지 테스트된다.

캐들에서 API 정의를 작성하는 작업은 간단하다. 주로 해당 캐들 코드 기본 파일에서 REST 바인딩과 오픈API 바인딩을 둘 다 선언해야 한다. 캐들에서는 키워드를 ‘데코레이터(decorators)’라고 하며 앞에 @를 붙이면, 파일을 작성자가 직접 읽을 수 있다. 

정의는 서비스 정의부터 시작해야 한다. 서비스에 이름을 부여하고 더 중요한 것은 버전 번호를 부여하는 것이다. 그다음에는 엔드포인트에 대한 URI로 서버 정의를 추가할 수 있다. 광역적으로 분산된 시스템에 유용한 이 기능은 API를 이용할 수 있는 지역과 같은 추가 매개변수를 추가할 수 있다. 이는 분명히 애저를 염두에 두고 설계된 것이지만 엔드포인트가 여러 개인 모든 분산 시스템에 도움이 된다.

다음으로는 API에서 사용하는 루트(route)와 리소스를 정의한다. 루트란 서비스 URI에 관한 리소스에 대한 경로이며 API 연산을 둘러싸는 이름공간에 연결된다. 연산은 예상되거나 기능에 의한 HTTP 동사를 사용해 정의된다. 이때 이름이 사용되는 곳에 컴파일러가 API 생성 시 적절한 동사를 추가한다. 이를 통해 REST API 호출의 요청 보디를 정의할 수 있으므로 이를 사용해 JSON을 복잡한 API로 보내거나 비교적 기본적인 것이라면 그냥 간단한 텍스트를 보낼 수 있다. 반응에 대해서도 동일한 프로세스가 적용된다.

더 복잡한 API의 경우, 자동루트 옵션을 통해 매개변수를 사용하는 경로를 생성할 수 있다. 예를 들면, 사용자이름 또는 ID를 이를 경로에서 예상하는 API로 전달하는 경우다. 매개변수를 경로에 전달하는 것에 한정되지 않으며 URL 질의로 전달하는 방법이 있다. 

결과를 보면 REST API를 비교적 간단하게 정의할 수 있다는 것을 알 수 있다. 익스프레스(Express) 노드JS 애플리케이션 프레임워크와의 작업이 연상된다. 다시 말해 캐들은 API를 추상화하면서, 서비스 호출을 위한 URL를 구축하기 위해 만들어졌다는 것을 알려준다. 익스프레스와 같은 도구를 사용한 경험을 가지고 온다면, 개발자들이 새로운 언어에 대처하는 데 도움이 될 수 있다.
 

캐들로 표준 구축하기

캐들은 API 정의 작성 외에도 많은 일을 한다. 대표적으로 API 제공을 위해 반드시 사용되어야 하는 구조를 제공함으로써 개발팀을 대상으로 API 표준을 시행한다. 어쩌면 정의보다 더 중요한 기능이다. 캐들 정의에 이어 표준을 구축하는 작업은 라이브러리의 작성을 통해 이뤄진다. 라이브러리는 C#와 흡사한 구문으로 공통 함수를 위한 재사용 가능한 템플릿을 관리할 수 있다. 마이크로소프트가 이러한 템플릿을 애저 API 기능 구현에 활용하는 방식은 살펴볼 만하다.

예를 들면, REST API를 정의하고 API 기능을 상세히 기술하기 위한 일반 인터페이스를 만들 수 있다. 일단 라이브러리가 생기면, API 인터페이스를 확장해 라이브러리 템플릿을 사용할 수 있다. 루트에 매핑하고 적절히 태깅한다. 그다음으로는 모델 정의를 사용해 API를 만들고 예상되는 모든 반응을 열거한다.

캐들은 간단하게 API에 설명문을 추가할 수단을 제공한다. @doc 선언문을 사용하면 설명문을 작성할 때 결과적으로 생긴 오픈 API 정의로부터 추출될 수 있는 설명문을 포함할 수 있다. 이 방법은 빠르고 간단하다. 마이크로소프트도 이 방법으로 애저 API 설명문의 많은 부분을 작성한다. API 설계자들이 API 설계의 본체뿐만 아니라 사용하는 모든 라이브러리에 설명문을 추가할 때 이 방법을 활용하도록 장려해야 한다.

캐들에는 마음에 들 만한 점이 많다. 한 번 보면 “왜 진작에 나오지 않았을까?”라는 생각이 들며, 도메인 특화 언어로 매력이 많다. 캐들은 논리적으로 API를 구축하고 제한할 수단을 제공한다. 따라서 아키텍트는 API가 할 수 있고 제공할 수 있는 것에 대한 소신을 지킬 수 있고, API 개발자들은 자신들의 코드가 할 수 있는 것과 일치하는 정의를 빨리 구축할 수 있는 자유를 얻을 것이다. 캐들은 양쪽 클라이언트 개발자가, 나아가 테스트 도구가, 일관된 API 정의를 접하게 해준다.
editor@itworld.co.kr