*잠깐, 위시켓은 2022년 시밀러웹 방문자 수 기준, 국내 1위 IT아웃소싱 플랫폼입니다. 현재 10만 이상의 개발업체, 개발 프리랜서들이 활동 중이며 무료로 프로젝트 등록이 가능합니다. 프로젝트 등록 한 번으로 여러 개발업체의 견적, 예상기간, 포트폴리오 등을 한 번에 비교해 보세요📝



API(Application programming interface)는 소프트웨어 사이의 통신 규약을 정의한 것으로서, 시스템 간 연결의 핵심 기술입니다.

이러한 인터페이스는 개발 팀으로 하여금 데이터, 기능, 응용프로그램을 사용해서 새로운 제품을 간단히 만들 수 있도록 해줍니다.

프로덕트 매니저로서, ‘API’가 작동하는 방식과, ‘API’가 팀과 회사에 가져다줄 거대한 잠재력을 이해하는 것은 매우 중요합니다.

왜 ‘API’를 사용하나요?



‘API’는 조직이 새로운 상황으로 빠르게 확장하거나, 새로운 시장에 적응할 때 상당히 많은 노력을 줄여주는 열쇠가 될 수 있습니다.

이를 통해서, 팀은 기존의 인프라를 활용하고 개발 시간을 월 단위에서 주 단위까지 줄일 수 있습니다.

아래 글을 빌려, 프로덕트 매니저로서, ‘API’에 대해서 알아야 할 중요한 개념들을 살펴볼 것입니다. 이러한 이해를 바탕으로 여러분은 여러분의 팀원들과 자신감 있게 ‘API’에 대해 이야기할 수 있는 탄탄한 기반을 갖게 될 것입니다.



오픈 ‘API’와 내부 API

‘API’가 어떻게 작동하는지 이야기하지 전에, API 사이의 작은 차이점에 대해 알아보겠습니다. 우리는 API를 오픈 ‘API’와 내부 API 두 가지 그룹으로 분류할 수 있습니다.

우선 내부 ‘API’는 사내 엔지니어링 팀에 의해 구축되어, 회사 내부의 마이크로 서비스끼리 통신할 때 사용하는 회사 내부 API를 의미합니다. 이는 오직 내부적으로 데이터 전송과 같은 자체 응용프로그램의 요구사항을 충족시키기 위해 사용됩니다.

반면 오픈 API는 외부와 공유되기 위해 설계되었습니다. 이를 통해 개발자는 API가 기능적으로 제공하는 정보를 이용해서 응용프로그램을 구축할 수 있습니다.

슬랙(Slack)은 오픈 API를 제공하는 회사 중 하나입니다. 따라서 여러분은 플랫폼에서 메시지를 보내고, 알림을 생성하고, 그룹을 만드는 응용프로그램을 만들 수 있습니다.

오픈 API	내부 API
사용 가능한 항목들을 제공해서 외부 개발자로 하여금 응용프로그램을 구축할 수 있도록 개발됨	특정 응용프로그램의 요구사항을 위해 팀에 의해 구축됨

요청(Request)과 응답(Response)



쉽게 말해서 API는 요청과 응답으로 이루어져 있습니다. 요청은 우리가 API와 상호작용할 수 있도록 도와주고, 응답은 상호작용의 결과물입니다.

하나의 예를 가져와 보겠습니다. AccuWeather API를 사용해서 우리는 특정 지역의 날씨 정보를 요청할 수 있습니다. 이를 위해 아래의 행동들이 반드시 수행되어야 합니다.



API의 사용자로서 여러분은 AccuWeather API에게 요청을 보내야 합니다.

1. 이 요청의 바디(body)에 여러분은 API에게 어느 지역의 날씨 정보를 원하는지 명시해야 합니다. 이 설명이 전달되는 방식은 API 문서에 설명되어 있습니다(이 내용에 대해서는 잠시 후에 설명하겠습니다).
2. AccuWeather는 “JSON”의 형태로 된 메시지를 통해 요청된 정보를 반환합니다.

API 문서에는 요청 정보가 어떻게 시스템에 전달되며, 시스템이 그것을 어떠한 방식으로 반환하는지 상세히 명시되어 있습니다.



HTTP 메소드

API를 요청할 때 HTTP 메소드라고 불리는 것을 지정해야 합니다.

이러한 메소드는 상호작용에서 주어진 리소스를 통해서 어떤 행동을 취할지 나타내는 역할을 합니다.

여러분이 모든 HTTP 메소드에 대해 아실 필요는 없습니다. 가장 많이 사용하는 버전인 1.1에서 우리는 상황에 따라 9개의 메소드를 사용합니다. 제품 담당자가 가장 많이 사용하는 메소드는, 정보를 생성하거나 얻을 수 있는 ‘POST’와 ‘GET’입니다.

다음은 가장 일반적인 HTTP 메소드에 대한 요약입니다.

• POST: 새로운 리소스를 생성하기 위해 사용합니다. 예를 들어, 우리가 슬랙의 오픈 API를 이용해 새로운 문자 메시지를 생성할 때, 우리는 POST(생성) 방식을 사용합니다.
• GET: GET(읽기)은 오직 수정 불가능한 데이터를 읽기 위해 사용합니다. 이는 보안을 위해 존재합니다. 예를 들어 AccuWeather API를 사용할 때 우리는 GET 방식을 사용하여 지역에 대한 정보를 요청해야 합니다.
• PUT: PUT은 데이터를 갱신하거나 복사할 때 사용합니다. 예를 들어 사용자의 이메일 정보를 갱신해야 하는 경우에 PUT을 사용합니다.

다른 메소드들도 존재하지만 우리는 가장 많이 사용되는 3가지에 집중할 것입니다. 따라서 여러분이 3가지를 전부 다 아신다면, 여러분은 충분히 알고 계시는 것입니다.



엔드 포인트는 API가 소프트웨어 혹은 프로그램과 연결되고 있는 위치입니다. 다시 말해, 엔드 포인트는 요청이 만들어지고, 시스템으로부터 상호작용을 통해 응답을 받는 프로그램이나 사용자의 특정 디지털 위치입니다.

AccuWeather의 공공 API 엔드 포인트의 예를 들어보겠습니다.

GET http://dataservice.accuweather.com/currentconditions/v1/{locationKey}

여기서 엔드 포인트는 currentconditions이며, 사용자는 GET 방식을 통해 특정 지역의 현재 기후 데이터에 대한 요청을 보낼 수 있습니다.

우리는 locationKey라는 매개변수를 요청 시에 함께 전송합니다. 이는 API에게 우리가 찾고 있는 지역을 명시하는 데 사용합니다.

여기서 주목할 만한 점은 동일한 엔드 포인트가 둘 이상의 HTTP 메소드와 함께 작동할 수 있다는 점입니다.

여러 방식을 동시에 사용하는 것은 안되지만(동일한 요청에서 GET과 POST를 함께 수행할 수는 없습니다), 경우에 따라서 같은 엔드 포인트 내에서 정보를 가지고 오거나 편집할 수 있습니다.


응답 코드(혹은 상태 코드)

• API와 상호작용하는 과정에서 여러분은 다양한 타입의 메시지를 받을 것입니다. 이러한 응답 코드는 요청이 성공했는지, 실패했는지를 나타냅니다. 일반적으로: 200번대 코드는 성공을 의미합니다.

• 400번대 코드는 제공된 정보를 기반으로 한 오류를 의미합니다(예를 들어 필요한 매개변수가 전달되지 않은 경우)

• 500번대 코드는 API 서버의 문제를 나타냅니다.

이 메시지들은 API에 따라 매우 다양한 케이스가 존재합니다. 메시지와 응용 프로그램의 자세한 사용 사례 정보에 대해서는 API 문서에 잘 명시되어 있습니다(일반적으로 에러 처리 방법은 API 문서에 설명되어 있습니다).

인증(Authentication)과 권한(Authorization)


대부분의 API는 그들의 서비스에 요청을 보내기 이전에 사용자 인증을 필요로 합니다.

오픈 API의 경우, 사용자는 일반적으로 요청이 전송될 때 요청에 추가될 자격 증명에 접속해야 합니다. 이러한 자격 증명은 특정 서비스와 상호작용하는 개인이나 회사를 식별하는 역할을 합니다.

예를 들어, 제가 AccuWeather의 API를 통해 제 위치에 대한 날씨 데이터 요청을 보낼 때 응용프로그램은 이 정보를 요청하는 사람이 그 누구도 아닌 저인 것을 알고 있습니다.

또한 인증은 API 기능에 대한 접속을 제한하거나 허락하는 역할도 합니다.

특정 그룹의 사람들이 응용 프로그램을 통해 특정 데이터에 접속하거나 편집하지 못하도록 하려는 경우 그들의 자격 증명을 통해 해당 데이터에 대한 제한을 생성합니다.

이렇게 하면 이 그룹이 권한이 없는 작업을 수행하려고 할 때 API가 해당 요청에 대한 응답으로 오류 메시지를 전송합니다.


요약:

인증: API에 누가 서비스와 상호작용을 하고 있는지 나타냅니다. 대부분의 경우, 사용자 인증은 다음으로 이루어져 있습니다. (ex: 아이디, 비밀번호, 액세스 토큰)

권한: 권한은 API를 구축한 팀에 의해 정의됩니다. 이는 어떤 사용자 그룹이 그들의 서비스와 상호작용하는 것에 대해 허락 여부를 나타냅니다.

API 문서


API 문서는 API를 제공하는 제품 담당자와의 주요 연락 지점입니다. 이곳에서 API의 기능들이 나열되어 있고, 어떻게 응용프로그램과 상호작용할 수 있는지 설명되어 있습니다.

몇몇 경우에 브라우저에서 직접 요청이 가능한 위치에 문서가 있을 수 있습니다(일반적으로 API의 레퍼런스 페이지에 존재합니다).

이 페이지는 요청이 처리되고 응답이 전송되는 방식에 대해 설명합니다. 게다가 문서는 각 종류의 액세스와 계획의 각 유형이 가진 제한이 무엇인지 분명히 보여줍니다.

여러 계획에서 작동하는 API의 경우, 각 계획에서 어떻게 작동하는지(그리고 얼마만큼의 요청까지 주어진 시간 내에 처리할 수 있는지) 설명하는 일종의 테이블이 존재합니다.

마지막으로, 문서는 요청에 전달할 수 있는(혹은 꼭 필요한) 매개변수를 포함해야 합니다. 이는 요청을 위해 어떤 정보가 필요하고, 어떠한 방식(HTTP 메소드)으로 전달해야 하는지도 포함합니다.

AccuWeather의 엔드 포인트 예시에서, 문서는 API가 사용자가 원하는 것이 무엇인지 이해할 수 있도록 매개변수(locationKey)를 전달하는 방법을 명확하게 설명하고 있습니다.

이러한 방식으로 사용자와 API는 ‘같은 언어’를 사용해 통신하며 서로가 원하는 것을 얻을 수 있습니다.


문서에서 우리가 발견할 수 있는 내용들:

인증 지침: 서비스와 상호작용할 때 API에 본인이 사용자임을 인증하는 방식입니다.

엔드 포인트: 어떤 엔드 포인트에서 접속이 가능한지, 어떤 리소스가 제공되어야 하는지, 어떤 HTTP 방식이 사용되어야 하는지에 대한 정보입니다.

리소스: 무엇이 API에 유효한지, 슬랙의 예시로 되돌아가서, 문서는 메시지를 보내고, 그룹을 만들고, 알림을 생성할 수 있음에 대해 설명해야 할 것입니다.

요청 포맷: 요청을 보내는 방식과, 어떤 매개변수들이 전달될 수 있는지(혹은 꼭 필요한지)에 대한 설명입니다.

응답 포맷: API가 요청에 대해 어떻게 응답하는지에 대한 설명입니다. 여기서 API가 JSON(AccuWeather의 예시에서 이야기했던) 이외의 방식으로 결과를 반환할 수 있다는 점을 주목해야 합니다. 이러한 응답 방식의 차이는 REST, RPC, SOAP와 같은 API 아키텍처나, 응용 프로그램의 목적에 따라 달라집니다.

응답 코드: 상황 별 응답 코드에 대한 설명과, 그리고 받은 에러를 처리하는 방법에 대한 설명입니다.

API가 프로덕트 매니저에게 어떻게 도움이 될까요?


API는 기존에 사용하던 인프라를 재사용하기 때문에 새로운 제품을 만들고 가설을 입증하는 것을 더 빠르게 만들어주는 잠재력을 가지고 있습니다.

프로덕트 매니저는 오픈 API를 통해 여러 테스트를 진행하거나, 제품을 성장시킬 수 있는 기회를 찾아낼 수 있습니다.

• 그 API가 프로세스를 최적화하는데 어떤 도움이 되나요?

• 자체 인프라를 구축해야 하나요? 아니면 타사의 인프라를 사용할 만한 가치가 있나요?

• 이게 제 비즈니스 모델에 어떤 영향을 미치나요?

이들은 오픈 API를 여러분의 제품에 도입하는 것을 고려할 때 지표로 삼을 만한 질문들입니다. 마지막으로 사업을 확장하기 위해 API를 구축하는 것은 여러 시장의 플레이어들이 이전부터 널리 사용해온 방식입니다.

서비스를 다른 회사에 개방하여 인프라를 아웃소싱하는 것은 새로운 시장(B2B)에 진입하고 기하급수적으로 성장할 수 있는 기회이지만, 이것은 또 다른 문제입니다.


국내 1위 IT아웃소싱 플랫폼 위시켓에 프로젝트를 등록해 보세요.

6만여 건의 데이터를 바탕으로 프로젝트 견적을 상담해 드립니다.