기고 | 비즈니스를 강화하는 내부용 API를 설계하는 법

지난 10년에 걸쳐 웹 애플리케이션 개발자는 API 설계자가 됐다. 하지만 대부분의 조직은 개발자를 API 설계자로 인식하지 않으며, API를 설계의 산물로 보지도 않는다. 이는 개발자의 생산성을 저해하는 요인이 된다. AI 등장 이후 그 어느 때보다 API가 많아지면서 이런 문제가 더욱 악화되고 있다.

이 글에서는 종종 소홀히 다뤄지지만 의도치 않게 비즈니스에 큰 도움이 되는 내부용 API에 대해 살펴보고, 조직이 이런 API를 어떻게 관리할 수 있는지 설명한다.

우연히 비즈니스를 이끌게 된 내부용 API

일반적으로는 조직이 의도적으로 비즈니스를 구축한 API가 주목받는다. 기업의 제품과 시장 진출 전략에 핵심적인 역할을 하는 스트라이프(Stripe), 트윌리오(Twilio), 인스타그램(Instagram) API가 대표적이다. 이런 API는 잘 검토된 설계로 시작해 여러 차례의 개선, 정제, 문서화 과정을 거쳐 최종 사용자인 대중에게 제공된다.

반면 조직이 우연히 비즈니스를 구축하게 된 API도 있다. 처음부터 의도하거나 계획하지는 않았지만, 결과적으로 비즈니스의 핵심적인 역할을 하게 된 내부용 API다.

• 프론트엔드와 백엔드 API: 2000년대 초반부터 RESTful API 설계가 부상하면서 웹 애플리케이션의 프론트엔드는 주로 API를 통해 백엔드와 통신하게 되었다.
• 서비스 간 API: 2000년대 초반부터 서비스 지향 아키텍처가 등장하면서 소프트웨어 조직은 각 팀이 일련의 서비스를 담당하는 구조로 변화했다. 소수의 아키텍트가 하향식으로 모든 API를 설계하는 대신, 개별 팀이 자체적으로 API를 설계하는 등 점점 더 분산화된 방식으로 운영되고 있다.

이런 API는 보통 대외용 API보다 그 수가 더 많으며, 개발자가 전적으로 설계하고 관리한다.

내부용 API에 설계가 중요한 이유

외부 사용자가 한 번도 본 적 없는 API를 개발자가 설계한다는 것이 무슨 문제가 될까? 제품 관리자와 비즈니스 담당자가 코드를 들여다보지 않았다면, 내부용 API까지 살펴볼 필요가 있을까?

문제는 개발자 주도의 설계 결정이 좋은 사용자 경험을 제공할 역량과 개발 속도(즉, 비즈니스 민첩성)에 모두 영향을 미친다는 점이다. 그리고 이 2가지 사이에는 긴장 관계가 존재한다.

사용자 관점에서 이상적인 API 설계는 가능한 한 일반적인 기능을 갖추는 것이다. 예를 들어, 은행 API를 사용할 때는 잔액을 조회하는 함수 하나, 잔액을 변경하는 함수 하나만 있는 것이 이상적이다. 잔액 조회를 위한 함수가 수십 개라면 잘못된 함수를 호출할 가능성이 훨씬 높아진다.

하지만 개발자 관점에서는 구체적인 API를 구축하는 것이 더 쉽다. 함수가 구체적일수록 개발자가 최적화하기 쉽기 때문이다. 예를 들어, 개발자에게 가장 빠른 뱅킹 앱을 만드는 방법은 앱 백엔드가 프론트엔드에 필요한 정보만 정확히 전송하고 그 이상은 전송하지 않는 것이다. 내부용 API는 사용 편의성보다는 개발자의 성능 최적화 용이성을 위해 설계되는 경향이 있다.

외부의 제약이나 지침이 없다면, 개발자들은 자연스럽게 장기적인 개발 효율성이나 API의 플랫폼 활용 가능성보다는 즉각적인 최적화와 사용자 경험 증진에 치중하게 된다.

개발자 주도 설계의 힘을 활용하기

현재 API 생태계를 바라보는 2가지 관점이 있다. 하향식 API 설계의 관점에서 보면, 통제를 벗어난 API의 무분별한 확산을 우려하며 사양 우선(spec-first) 접근으로 이를 관리하려 할 것이다.

하지만 더 효과적인 대안이 있다. API 설계의 개발자 주도적 특성을 인정하고 협업을 수용하는 것이다. API 설계가 반드시 하향식이나 아키텍트 주도, 또는 상향식 개발자 결정으로만 이루어질 필요는 없다. API 설계를 하나의 협업 과정으로 바라보면 어떨까?

다음은 개발자 우선 모델에서 협업적 API 설계가 어떤 모습인지 보여주는 예시다.

• API 개발자는 특정 목적을 위해 내부 API를 설계하면서 사용자와 동료 API 개발자로부터 즉각적인 피드백을 받는다. 설계는 단순한 정적 문서가 아니라 테스트나 모형의 풍부한 정보로 보완될 수 있다.
• API 사용량이 늘어날수록 개발자는 더 많은 피드백을 받고 API를 업데이트한다.
• 이전 버전의 API는 저장되고 문서화되며, API를 업데이트한 이유가 모두에게 명확히 전달된다.
• API는 ‘유기적인 설계’와 함께 발전해 개발자가 현재 사용 사례에 맞게 API 구현을 최적화할 수 있게 한다. 또한 사용자가 원활하게 API를 사용하도록 하며, 사용자와 협업자가 요구사항이 변경될 때 피드백을 제공하게 한다.
• 더불어, 이러한 유기적 설계는 실제 앱의 동작 패턴을 기준으로 삼아 구현이 업데이트될 때마다 자동으로 갱신된다.

소프트웨어 개발 전반에 API 개발 관점으로 접근하면 생산성을 획기적으로 높일 수 있다. 하지만 코드와 문서를 공유하는 것만큼 API 설계를 공유하기 쉬울 때만 가능하다.

개발자에게 분산형 API 개발의 자율성을 부여할 때, 소프트웨어 조직의 발전 속도는 놀라울 정도로 빨라진다. 신속하고 분산된 개발 방식은 조직력이나 협업 체계를 약화시키지 않는다. 핵심은 생산적인 협업에 있다.

Jean Yang은 포스트맨(Postman)의 제품 책임자다.
[email protected]