API의 기초: API 설계에 대해 알아야 하는 모든 정보

* 본 아티클의 원문은 2020년 10월 22일 Google Cloud 블로그(영문)에 게재되었습니다. 

애플리케이션 프로그래밍 인터페이스, 즉 API는 소프트웨어가 상호 간에 통신하는 방식입니다. API는 기본 시스템의 복잡함을 추상화하기 때문에 연동되도록 의도되지 않았던 시스템까지 색다른 방식으로 연결할 수 있습니다. 따라서 API는 최신 디지털 환경에서는 물론 오늘날 가장 흥미로운 비즈니스 기회를 실현하는 데에도 핵심 요소로 각광받고 있습니다. 

하지만 API가 제공하는 가치는 API를 통해 액세스할 수 있는 기능 및 데이터뿐 아니라 API의 설계 방식에 의해서도 좌우됩니다. 많은 API가 통합용으로 설계됩니다. 즉 시스템을 연결하되 API의 추후 용도는 염두에 두지 않는 일회성 프로젝트에 그치는 것입니다. 가장 가치가 높은 API는 대체로 개발자의 작업을 간소화하기 위해 설계된 것이므로 추후 다른 개발자의 활용을 염두에 둔 설계인 경우가 일반적입니다. 이것을 소비용 설계라고 합니다. 

이 차이는 비즈니스의 효율성과 혁신 역량에 큰 영향을 미칠 수 있습니다. 소비용으로 설계된 API를 사용하면 가치가 높은 기능과 데이터를 재사용할 수 있기 때문에 개발자가 서로 다른 API를 모듈식으로 조합하여 새로운 디지털 환경을 조성하거나 새로운 전략을 지원하는 데 사용할 수 있습니다. 파트너 참여 간소화 또는 디지털 생태계 참여 촉진 등을 목표로 한다면 이런 방식으로 API를 활용하는 것이 필수적입니다. 

반면 통합용으로 설계된 API는 당장의 프로젝트 요구사항을 해결해 줄 수는 있지만 개발자가 이 API를 추후에 다른 용도로 활용하기는 어렵습니다. 이러한 API는 이후 다른 개발자가 쉽게 이해할 수 있는 방식으로 설계되지 않았을 뿐 아니라 향후 개발자가 예상하는 방식으로 작동하지 않을 수 있습니다. 이 경우 결국 새 API를 만들어야 하므로 업무 부담과 시간 지연을 초래합니다. 애초에 보다 광범위한 용도를 염두에 두고 API를 설계했다면 일어나지 않았을 일입니다. 

API 설계자가 가치와 개발자 생산성을 극대화하는 API를 빌드하려면 어떻게 해야 할까요? 이미 Google Cloud 블로그에서 이 주제를 여러 번 다뤘기에 이번 게시물에서는 API 설계에 대한 도움말과 권장사항에서 가장 유용한 정보를 모아 제공해 드립니다.

다양한 접근방식: REST, RPC, GraphQL

API별로 수반되는 시스템 상호작용 방식과 설계 규범이 각기 다르기 때문에 본격적인 시작에 앞서 다양한 API 설계 모델을 두루 살펴보는 것이 좋습니다. 자세한 정보는 API 설계: gRPC, OpenAPI, REST 및 그 용도의 이해, REST와 RPC 비교: 해결하려는 문제에 따른 API 선택, GraphQL: API 소비자에 대한 일관된 접근방식 수립, 웹 API가 항목 중심이어야 하는 까닭을 참조하세요. 

종합적인 API 설계 개요

다양한 API 설계 주제를 자세히 알아보려면 API 웹 설계: 잃어버린 고리: 개발자가 선호하는 인터페이스 만들기 권장사항이라는 eBook을 통해 기본 지식을 탄탄히 다질 수 있습니다. 2014년부터 Google 내부에서 사용되면서 Cloud API 및 기타 Google API를 설계할 때 가이드로 활용되는 Google Cloud API 설계 가이드도 유용합니다. 또한 API 설계 권장사항 및 일반적인 문제에는 API 설계와 관련된 각종 주제의 Q&A가 수록되어 있으므로 읽어보기를 권해드립니다.

구체적인 과제 및 권장사항 

위의 기사에서는 여러 주제를 폭넓게 다루었지만 API의 장기적인 가치에 영향을 미칠 수 있는 보다 세부적이고 구체적인 API 설계 과제도 다수 살펴봤습니다.

예를 들어 API는 여러모로 관계를 정의하는 방식입니다. 소매업체 API의 경우 정보 모델이 고객, 주문, 카탈로그 항목, 장바구니 등과 같은 항목 간의 관계를 설명하기도 합니다. 마찬가지로 은행 API는 계좌가 어떤 고객의 소유인지, 각 융자금 또는 인출액은 어떤 계좌에 해당되는지 표현합니다. API 개발자가 관계를 표현하는 가장 일반적인 방법은 노출하는 항목의 필드에 데이터베이스 키 또는 프록시를 노출하는 것입니다. 하지만 이 방법은 적어도 웹 API에 있어서는 웹 링크에 비해 몇 가지 단점이 있습니다. 그 이유를 확인하려면 API 설계: API에서 관계를 표현하는 데 키가 아닌 링크를 사용해야 하는 이유를 참조하세요. 

마찬가지로 API URL을 작성할 때 사람이 인지하기 쉬운 이름을 이용한 URL을 사용해야 하는 경우와 정적인 숫자 ID를 이용한 URL을 사용해야 하는 경우를 알면 다소 혼란스럽더라도 큰 도움이 됩니다. 예를 들어 은행 계좌의 경우 숫자 ID를 사용하지 않으면 신뢰성 높은 참조의 역할을 하기 어려울 수 있습니다. 계좌 소유자에 관한 세부정보(예: 이름, 주소, 결혼 여부)가 바뀌거나 불확실한 경우(생년월일, 출생장소)도 있기 때문입니다. 소유자의 ID에 신뢰성이 있더라도 계좌의 소유권이 바뀔 수도 있습니다. 따라서 정적인 숫자 ID가 가장 신뢰할 수 있는 선택사항입니다. 이 주제를 보다 자세히 알아보려면 API 설계: 이름과 ID 중에서 URL 방식 선택하기를, 사람의 가독성과 시스템 안정성을 알맞게 절충한 API 설계에 대한 자세한 설명을 원한다면 웹 API에서 URL 설계의 잘못된 이분법을 읽어보세요.

소비용으로 설계된 API는 원래 개발자를 위한 소프트웨어 제품이기 때문에 여타 소프트웨어 제품처럼 반복 및 개선이 가능합니다. 하지만 새 API의 버전 관리 방법에는 다소 차이가 있기 때문에 API 설계: 나에게 맞는 버전 관리 및 API 버전 관리에 대한 일반적인 오해를 주의깊게 읽어보시기 바랍니다. 

마지막으로 API는 검색 엔진에서 단일 페이지 애플리케이션이 색인되는 방식에 영향을 미칠 수 있으므로 이와 관련된 비즈니스 니즈가 있는 경우 API 설계 및 SEO에 관한 2부작 시리즈를 길잡이로 삼으시기 바랍니다. 

API의 활용도 높이기

위의 정보를 토대로 한다면 보다 강력하고 사용자 친화적이며 다용도로 활용할 수 있는 API를 만들 수 있을 것입니다. 소비 중심 API의 주요 역할 중 하나가 재사용을 촉진하는 것이므로 보다 다양한 애플리케이션을 더욱 신속하게 빌드할 수 있는 새롭고도 무수히 많은 길이 펼쳐지게 됩니다. API를 통해 비즈니스 성과를 도출하는 방법을 보다 자세히 알아보려면 Google Cloud Next ‘20: OnAir의 API 관련 주제 모음을 확인해 보세요. 지금 바로 시작해 보세요.