API 설계란?

API 설계는 개발자와 사용자에게 데이터 및 애플리케이션 기능을 제공하는 애플리케이션 프로그래밍 인터페이스(Application Programming Interface, API)의 개발 프로세스를 말합니다. API는 기업의 운영 및 제품에서 파트너십 전략에 이르는 모든 요소에 새로운 기능을 추가하여 현대적인 기업에서 매우 중요한 역할을 합니다. 대부분의 기업은 API 프로그램을 적용할 수 있는지의 여부가 아니라 어떻게 적용할 수 있는지에 대한 적용 방법을 알고 싶어합니다.

효과적인 API 프로그램은 비즈니스의 전체 전략을 기반으로 구축하고 기업의 목표 달성을 지원해야 합니다. 다음 세가지 질문에 분명한 답을 제시할 수 있다면 훌륭한 전략을 위한 기반을 갖추었다고 할 수 있습니다.

1. API를 구현하고자 하는 이유는 무엇인가?
2. API를 통해 실현하고자 하는 구체적인 성과는 무엇인가?
3. 성과를 실현하기 위해 어떤 방법으로 API 프로그램을 실행하고자 하는가?

이유

API를 구현하고자 하는 이유에 대해 잘못 이해하는 경우가 많습니다. 우선, API의 가치에 집중하기보다는 API로 인한 효과의 가치를 생각하는 것이 좋습니다. 기억할 것은 API 자체가 아니라 기업의 핵심 비즈니스가 중요하다는 점입니다. API는 기업이 전달하는 기존의 가치에 새로운 방식으로 접근할 수 있는 채널을 제공할 때 의미가 있습니다.

또 다른 흔한 오해는 API 자체의 가치에 대해 사용자가 대가를 지불할 준비가 되어 있어야 한다는 믿음입니다. 이는 API 자체가 제품인 경우에만 해당됩니다. 대부분의 모델에서는 그렇지 않습니다. API는 주로 영업, 제휴 마케팅, 브랜드 인지도 등 다른 메트릭을 이끄는 동인입니다. 사용자에게 API가 제공하는 가치는 API 호출(서비스 요청 및 응답)에 따른 결과이지 호출 그 자체가 아닙니다.

Cutter Consortium과 Wipro가 152개 기업을 대상으로 실시한 설문조사에 따르면, API 프로그램 구축을 위한 주요 비즈니스 추진 요소는 새로운 파트너십 개발, 수익 증대, 새로운 비즈니스 모델 활용, 시장 출시 시간 단축, 새로운 유통 채널 개발 등입니다. 기술 측면의 주요 추진 요소는 애플리케이션 통합 개선, 모바일 통합 개선, 더 많은 장치에 대한 연결 지원 등입니다. API에 대한 투자를 확신하고 선택하기 위해서는 기업이 얻을 수 있는 이점이 분명해야 합니다.

성과

두 번째 질문은 "API를 통해 실현하고자 하는 구체적인 성과는 무엇인가?"입니다. 다시 말해, "API가 실제로 어떤 역할을 하고 비즈니스 전략의 큰 그림에서 어떠한 영향을 주는가?"입니다.

기업의 내부 및 외부 관점을 통해 API로부터 실현하고자 하는 성과를 정의하는 데에 도움이 될 수 있습니다. 내부 관점은 기업이 가지고 있는 구체적이고 가치 있는 자산을 뜻합니다. 제공하는 서비스와 리소스의 가치가 높고 고유할수록 API 프로그램에 더욱 적합하다고 할 수 있습니다.

고유한 데이터를 보유한 기업은 API를 통한 데이터 액세스를 허용함으로써 리소스를 활용할 수 있습니다. 고유한 콘텐츠, 데이터, 서비스는 API에 대한 액세스의 가치를 매우 높일 수 있습니다.

비즈니스에서 API의 역할이 무엇인지 결정할 때에는 내부 관점과 외부 관점을 모두 검토해야
합니다. 원하는 성과에 대한 결정은 주로 이 두 가지 관점을 종합한 것입니다.

API 구현을 원하는 이유가 자주 변경되지는 않지만 성과는 시장, 기술적 고려 사항, 경제 상황 등 외부 요인에 의해 크게 달라질 수 있습니다. 자산의 가치에 대한 내부 지침이 변경될 수 있으며 이 또한 API를 통해 실현하고자 하는 성과에 영향을 줄 수 있습니다.

방법

마지막 질문인 "원하는 성과를 실현하기 위해 어떤 방법으로 API 프로그램을 설계할 것인가?"는 구현과 실행에 관한 질문입니다.

팀은 다음 사항을 검토해야 합니다.

• API를 구축하기 위해 사용하는 기술은 무엇인가?
• API는 어떻게 설계되는가?
• API는 어떻게 관리되는가?
• API를 기업 내부에서 확산하거나 외부에 공개하는 방법은 무엇인가?
• 이용 가능한 리소스는 무엇인가?
• 팀원은 누가 되어야 하는가?
• 수립한 비즈니스 목표에 따른 결과를 어떻게 추적하는가?

API의 가치를 찾아내고 설명하는 것은 계속 반복해야 하는 과정입니다. 첫 단계는 사용자가 수행하고자 하는 업무를 설명하는 것입니다. 예를 들면, 다음과 같습니다.

• 긴급 상황 시 팀원에게 긴급 메시지 자동 전송
• 중요 파일을 백업하여 손실 방지
• 특정 이벤트를 감지하기 위해 샘플 데이터 수집

다음 단계는 업무를 수행하기 이전, 이후 또는 도중에 사용자에게 영향을 주는 특정 과제를 파악하는 것입니다.

• 여러 번 시도 후 이루어지는 전송의 신뢰성 확보, 장애 감지, 하나가 아닌 다수의 메시지 전송에 대한 우려, 사용자의 위치에 따라 다른 메시지 전송 시스템 통합
• 전송 대역폭 사용량을 최소화하는 동시에 안전한 파일 전송 보장
• 대용량 데이터를 처리하면서 실시간 상호 연계 시도

세 번째 단계는 사용자가 실현할 수 있는 잠재적 이점을 요약하는 것입니다.

• 위협에 대한 경고가 아닌 기회를 창출하는 다른 유형의 알림 전송
• 필요한 안정성이 확보된 경우 다른 스토리지 장치 제거
• 이벤트 기반으로 자동으로 작업 트리거

이러한 문제점을 검토할 때는 시야를 넓혀 지원, 도큐멘테이션, 개발자 포털 등 고객이 사용할 수 있는 모든 것을 나열해야 합니다. 그 다음 API 사용자가 업무를 완료하기 이전, 이후, 또는 작업 중에 장애가 되는 문제를 제거하거나 완화할 수 있는 방법 또는 작업을 방해하는 문제점이 무엇인지를 정리합니다. 그리고 API 사용자에게 제공하고자 하는 이점을 어떻게 실현할 것인지를 설명합니다.

이 과정을 거치면서 상기에서 제시한 세 가지 사례는 다음과 같은 결과를 가져올 수 있습니다.

• 메시지 전송을 위한 단일 호출을 사용하는 멀티채널 메시징 API로 메시지가 확실히 전송될 때까지 자동으로 재호출할 수 있는 기능 보장(예: Twilio, PagerDuty)
• 새로운 버전의 동기화 여부를 효율적으로 확인하는 최적화된 호출 기능을 갖춘 스토리지 동기화 API(예: Bitcasa, Box)
• 몇 가지 데이터 소스를 설정 가능한 스트림으로 집계하며, 필터링, 샘플링, 조작이 용이한 API(예: GNIP, DataSift)

마지막으로 API가 사용자 프로필을 준수하고 있는지의 여부를 분명히하는 몇 가지 설명을 작성하면 작업을 명확화하는데 유용합니다. 이러한 설명을 파악하기가 어렵다면 API 모델을 재고해야 합니다. 일부 API 기능을 추가, 수정, 조정, 제거해야 할 수도 있습니다. 혹은 API가 우수한 가치를 제공하지만 대상으로 하는 사용자 유형에 적합하지 않을 수도 있습니다.

적합성에 대한 설명을 요약하여 하나의 포괄적인 설명으로 추상화하면 그것이 바로 API의 가치 제안이 됩니다. 위의 메시징 API의 경우 다음과 같은 예를 들 수 있습니다.

Red Hat의 메시징 API는 엔터프라이즈 개발자에게 비즈니스에 매우 중요한 애플리케이션을 위한 안정적이고 지연 시간없는 문자 메시지 기능을 제공합니다. API는 빠른 통합을 위해 가장 많이 사용되는 프로그래밍 언어를 포함하는 소프트웨어 개발 키트(Software Development Kits, SDK)의 지원을 받기도 합니다.

경우에 따라서는 "단지 내부 API 개발에 너무 많은 작업이 필요하다"고 생각할 수도 있습니다. 그러나 내부 활용 사례에서도 가치에 집중하는 것이 중요합니다. 가치 제안을 제대로 정의하지 못하면 API의 가치를 다른 팀에게 전달하는 데에 어려움을 겪을 수 있습니다. 가치 제안이 제대로 정의되어 있으면 채택 과정이 용이하고 API 프로그램을 비즈니스의 핵심 요소로 활용할 수 있습니다.

API 프로그램의 가치를 정의할 때 아래와 같은 5가지 질문을 생각해 보십시오.

1. 사용자가 누구인가? 이 질문은 귀사의 입장에서 사용자와의 관계(기존 고객, 파트너, 외부 개발자), 사용자의 역할(데이터 과학자, 모바일 개발자, 오퍼레이션 담당자), 요구 조건이나 선호 사항이 무엇인지를 답해야 하는 것입니다.
2. 해결하고자 하는 사용자의 어려움이 무엇이고, 사용자에게 어떠한 이점을 제공하려 하는가? 이 질문에 대한 답변을 통해 가치 제안에서 정의된 고객의 비즈니스, 과제, 이점과 관련하여 중요한 요구 사항의 충족 여부(어려운 과제 또는 수익 창출 기회), 사용자가 개선하고자 하는 메트릭(속도, 수익, 비용 절감, 새로운 기능의 실현 등) 등을 확인해야 합니다.
3. API를 통해 지원하는 활용 사례는 무엇인가? 가치 제안을 통해 기업과 사용자에게 가장 효과적인 API에서 사용자 과제에 대한 솔루션을 확인합니다. 이러한 활용 사례를 해결할 수 있도록 API를 계획합니다.
4. 시간이 지남에 따라 사용자에 대한 가치를 어떻게 확장해 나갈 것인가? 향후 변화를 염두에 두고 가치 제안을 계획합니다. 즉, 내외부의 변화와 관련하여 향후 중요한 이정표는 무엇인가 하는 것입니다.
5. 내부적으로 기업에서 어떠한 가치가 창출되고 있는가? 내부적 이점을 고려하고 API를 통해 어떻게 비즈니스 내에서 가치를 제공할 수 있는지 생각해 봅니다.

API의 가치를 명확히 정의하는 것은 API 기반 프로그램을 설계하는 데 있어서 매우 중요한 단계입니다. 하지만 API 도입에는 비용이 들기 때문에 비용과 가치 사이에서 균형을 이루어야 합니다. API의 가치가 반드시 금전적으로 측정되는 것은 아니지만, 다음과 같은 실질적인 가치가 보장되어야 합니다.

• 기업의 기존 핵심 비즈니스가 무엇인가?
• 핵심 비즈니스를 가속화 또는 강화하기 위해 API가 어떻게 기여할 수 있는가?

경우에 따라 API를 통해 기업의 기존 비즈니스 모델 밖에서 완전히 새로운 비즈니스 기회를 찾기도 합니다. 이러한 경우에도 API는 기존 자산을 활용하여 새로운 방법으로 기회를 창출합니다.

요약하자면, 효과적인 API 프로그램을 설계하는 데 있어서 적합한 비즈니스 모델을 결정하는 것이 중요한 이유가 3가지 있습니다.

1. 적합한 비즈니스 모델을 결정함으로써 API가 기업에 가져다줄 가치에 집중할 수 있으므로 API 프로그램의 장기적인 활용을 결정하는 동기로 작용합니다. 이러한 결정이 없으면 효과적인 API 프로그램을 구축하고 운영하는 데 필요한 태스크를 완수할 수 있는 리소스를 확보하지 못합니다.
2. 적합한 비즈니스 모델을 결정함으로써 제품의 기능을 정의할 수 있고, 이에 따라 제3자의 요구를 충족하고 비즈니스를 창출할 수 있습니다.
3. 적합한 비즈니스 모델을 결정하면 기업 내 역할 및 책임, 그리고 API가 창출하는 가치의 어떤 부분이 누구에게 돌아가는지에 대한 고찰이 이루어집니다. 이는 API 활용으로 사용자가 얻게 되는 이점, 그리고 그것이 API 제공업체의 이점과 어떻게 균형을 이루는지 정의하는 것을 의미합니다.

좋은 API 설계에는 몇 가지 핵심 원칙이 있지만 이를 구현하는 방식은 다를 수 있습니다. 비유를 하자면, 모든 자동차에는 운전대, 브레이크 페달, 가속 페달이 있고 경고 표시등, 트렁크 개폐 방식, 라디오 등은 각 모델마다 조금씩 다를 수 있으나, 경험 많은 운전자가 렌트카를 운전할 줄 모르는 경우는 거의 없다는 것과 유사합니다.

이렇게 "바로 사용할 수 있도록 준비된" 설계가 바로 우수한 API 팀이 추구하는 설계 수준입니다. 즉, 자세한 설명없이 숙련된 사용자가 API를 바로 사용할 수 있도록 하는 것입니다.

간소화

API 설계의 간소화는 상황에 따라 달라집니다. 한 활용 사례에서 간단한 설계가 다른 사례에서는 복잡한 것일 수 있습니다. 따라서, API 방식의 간소화 정도는 상황에 따라 균형을 이루어야 합니다. 간소화는 다음과 같이 여러 수준에서 고려하는 것이 좋습니다.

• 데이터 형식: XML, JSON, 독점형 또는 혼합형
• 메소드의 구조: 광범위한 데이터 세트를 산출하는 일반적인 메소드 또는 특정 요청을 허용하는 구체적인 메소드로 주로 특정 활용 사례를 실현하기 위해 구체적인 순서로 호출됩니다.
• 데이터 모델: 기반 데이터 모델은 API를 통해 실제로 노출되는 것과 매우 유사하거나 매우 다를 수 있습니다. 이것은 활용성과 유지보수 용이성에 영향을 줍니다.
• 인증: 다양한 인증 매커니즘에는 각각 다른 장점과 단점이 있습니다. 상황에 따라 가장 적합한 매커니즘이 달라집니다.
• 사용 정책: 개발자의 권한과 쿼터는 이해하기 쉽고 작업이 용이해야 합니다.

API 간소화와 유연성은 양립시키기 어려울 수 있습니다. 간소화만을 고려하여 작성된 API는 지나치게 맞춤 설정되어 특정 활용 사례에만 적용될 수 있고, 다른 사례에 적용할 수 있는 유연성이 떨어질 수 있습니다.

유연성을 확보하기 위해서는 기반 시스템과 데이터 모델 등 오퍼레이션의 기반이 되는 잠재적 공간을 먼저 확인하고, 이러한 오퍼레이션의 일부 중 무엇이 실행 가능하고 중요한지 정의해야 합니다. 간소화와 유연성 간의 균형을 적절하게 조정하려면 다음을 수행합니다.

• 최소 단위 오퍼레이션을 노출: 최소 단위 오퍼레이션을 결합하면 처리 대상의 전체를 커버할 수 있습니다.
• 가장 일반적이고 중요한 활용 사례를 파악: 몇 가지의 최소 단위 오퍼레이션을 결합한 두 번째 레이어의 메타 오퍼레이션을 설계하여 이러한 활용 사례에 적용하세요.

물론, 애플리케이션 상태 엔진으로서의 하이퍼미디어(HATEOAS) 개념은 API와 클라이언트 오퍼레이션의 런타임 변경을 허용하기 때문에 유연성을 더욱 향상할 수 있습니다. HATEOAS는 버전 관리와 도큐멘테이션을 용이하게 하여 유연성을 높이는 데 도움이 되지만, API 설계에 있어서는 세심한 검토가 필수적입니다.

API 설계를 구상하기 위해서는 다음 5가지 질문을 고려해야 합니다.

1. 활용 사례를 지원하도록 API를 설계했는가? 주요 활용 사례를 선택한 후 다음 단계는 이러한 활용 사례를 지원하도록 API를 설계하는 것입니다. 빈도는 낮지만 혁신을 실현하기 위해 지원해야 할 활용 사례를 배제하지 않게 하려면 유연성이 중요합니다.
2. RESTful이 진정으로 필요한가? RESTful API는 매우 트렌디하지만 단순히 그러한 이유로 트렌드를 좇아서는 안 됩니다. RESTful이 적합한 활용 사례도 있지만 GraphQL 같은 아키텍처 스타일이 더 유리한 경우도 있습니다.
3. 활용 사례를 고려하지 않고 데이터 모델을 노출했는가? API는 실제 데이터 모델로부터 추상화된 레이어를 사용하여 지원해야 합니다. 일반적으로 API를 데이터베이스에 직접 연결해서는 안됩니다. 물론 경우에 따라 이러한 연결이 필요할 수도 있습니다.
4. 지리적으로 가장 중요한 지역이 어디이며, 그 중요성에 따라 데이터 센터를 계획했는가? API 설계에는 지연 시간과 가용성 등 기술 이외의 요소도 고려해야 합니다. 사용자 수가 많은 지역과 지리적으로 가까운 곳의 데이터 센터를 선택해야 합니다.
5. API 설계를 다른 제품과 동기화하고 있는가? API가 귀사의 유일한 제품이 아니라면 API 설계가 다른 제품의 설계와 연계되도록 해야 합니다. API 설계를 다른 제품과 완전히 분리하기로 결정할 수도 있습니다. 이러한 경우에도 다른 제품으로부터 API 설계를 분리하는 계획이 명확해야 하고 이를 내외부 모두에 명확하게 전달해야 합니다.

API 설계를 도입에 용이하도록 개선할 수 있는 핵심 기준은 "Time to first hello world"(TTFHW)입니다. 다시 말해, 개발자가 API를 사용하여 최소한으로 실행 가능한 제품을 만드는 데 걸리는 시간입니다. 이는 API를 어떻게 활용할지 테스트하고자 하는 개발자 입장에서 생각할 수 있는 좋은 방법입니다.

이 TTFHW 메트릭의 시작과 끝을 정의할 때 개발자 참여 프로세스를 가능한 한 많은 측면에서 지원하는 것이 좋습니다. 그리고 가능한 한 빠르고 편리하게 구현되도록 최적화하십시오.

프로세스를 빠르게 처리하는 것은 개발자에게 API가 효과적으로 구성되어 있고 예상대로 작동할 수 있음을 확신할 수 있게 합니다. 이러한 "성공의 순간"까지의 시간이 너무 길어지면 개발자를 놓칠 수 있습니다.

TTFHW 외에도 "Time to first profitable app"(TTFPA) 메트릭이 유용합니다. "수익성"은 API와 비즈니스 전략에 따라 좌우되기 때문에 좀 더 까다로운 문제일 수 있습니다. 이는 API 프로그램의 일부로 API 오퍼레이션과 관련된 측면을 고려해야 되기 때문입니다.

개발자 경험의 기반이 되는 두 가지 원칙은 다음과 같습니다.

1. 개발자에게 명확한 가치를 제공하고 분명한 과제나 기회에 대처하는 제품 또는 서비스를 설계합니다. 이는 금전적 가치 또는 기타 다른 가치일 수 있으며, 적용 범위, 브랜드 인지도, 고객 기반, 간접 영업, 개발자의 평판 등을 향상하거나 또는 단순히 우수한 기술을 사용하는 즐거움일 수 있습니다.
2. 제품에 쉽게 액세스할 수 있어야 합니다. 경량화된 등록 매커니즘(또는 매커니즘 부재), 테스트 기능에 대한 액세스, 우수한 도큐멘테이션, 다수의 간결한 무료 소스 코드 등을 포함할 수 있습니다.

API를 공개적으로 공개할지, 파트너에게만 공개할지 내부적으로 공개할지에 관계없이 대부분의 API 프로그램에는 개발자 프로그램이 있어야 합니다. 대상에 따라 프로비저닝의 정교한 수준은 다를 수 있습니다.

개발자 포털

개발자 포털은 개발자 프로그램의 핵심 요소입니다. 이는 개발자의 API 등록, 액세스, 활용을 위한 핵심 엔트리 포인트입니다. 개발자는 API에 간단하고 쉽게 액세스할 수 있어야 하며 즉시 사용 시작할 수 있어야 합니다.

TTFHW는 이를 측정할 수 있는 가장 좋은 메트릭입니다. 가입 절차의 효율성을 고려하여 단순화하고 신속하게 처리할 수 있도록 개선합니다. 권장하는 모범 사례는 개발자가 가입 절차 없이도 자신의 동작(요청 및 응답)을 검토하기 위해 API를 사용할 수 있도록 하는 것입니다. 또한, 시작 가이드와 API 참조 문서, 소스 코드 등 보조 콘텐츠가 있으면 빠른 학습에 도움이 됩니다.

에코시스템 파트너를 통한 가속화

API 제공업체로서 파트너와 벤더로 구성된 에코시스템에서 오퍼레이션됩니다. 파트너는 주로 자체적인 콘텐츠 배포 및 커뮤니케이션 네트워크와 수단을 갖추고 있습니다. 협업할 파트너를 식별하는 것은 API의 도입을 확산하는데 효과적일 수 있습니다. 일반적으로 이러한 제휴 관계는 API를 보완하고 결합하여 개발자에게 가치를 제공하는 경우 발생합니다.

개발자 환경을 평가할 때 고려해야 할 질문:

1. API의 가치를 5분 안에 어떻게 설명할 것인가? 개발자에게 API의 가치를 가장 효과적으로 제안할 수 있는 간결한 홍보 방법을 개발합니다.
2. TTFHW와 TTFPA는 무엇이며 어떻게 줄일 수 있는가? 이 질문은 엔드 투 엔드 TTFHW를 고려하여 API의 개발자 친화도를 개선할 수 있는 좋은 방법입니다. 개발자 환경에 추가할 수 있는 모든 요소(예: 포털)와 변화하는 모든 API 측면을 고려할 때 TTFHW와 TTFPA 메트릭을 생각하는 것이 좋습니다.
3. 개발자의 온보딩 프로세스가 무엇이며, 최대한 손쉽게 완료할 수 있는가? 이 문제는 귀사의 API 활용 사례와 연계되어야 합니다. 보다 민감한 API나 데이터 액세스에 대해서는 보안 수준도 더 강화되어야 하고 공식적인 프로토콜이 필요할 수 있습니다. 그 외에는 개발자가 조기에 성공할 수 있도록 모든 것이 단순하고 쉬워야 합니다(TTFHW).
4. API가 개발자에게 효과적으로 어필하기에 충분한 유연성을 지원하는가? 적합한 가치 제안을 찾아 개발자들이 API에 가입하면 매우 좋을 것입니다. 개발자의 성공을 지원하는것이 개발자 수를 유지하고 성장시킬 수 있는 비결임을 기억하십시오.
5. 문제가 발생했을 경우 개발자를 어떻게 지원하는가? Red Hat은 셀프 서비스 방식을 사용하여 확장성을 지원할 수 있다고 믿습니다. 대부분의 개발자 질문은 효과적인 도큐멘테이션, FAQ, 포럼 등으로 해결할 수 있습니다. 하지만 셀프 서비스에는 한계가 있고 심각한 문제나 복잡한 상황 (예: 송장 문제)에 대한 지원 메커니즘이 있어야 합니다.
6. 도큐멘테이션으로 혁신을 지원할 수 있는가? 일반적인 활용 사례에서 벗어나 새로운 작업을 시도하고자 하는 개발자에 대한 지원에는 무엇이 있을까요? 훌륭한 아이디어는 어디서든 나올 수 있습니다.