API가 무엇인가요?
기획자가 공부하는 API Part.1
PM으로 일하며 개발자들과 원활히 소통하기 위해 개발 지식의 필요성을 절실히 느끼고 있다. 특히, 최근 진행 중인 프로젝트에서 자주 등장하는 개념들을 이해하고자 공부를 시작했다. 이 글은 나처럼 비전공자로서 개발자들과 협업하며 비슷한 고민을 겪는 PM이나 기획자들에게 작은 도움이 되길 바라는 마음으로 작성되었다.
API란 무엇인가?
오늘 공부할 개발 지식은 API이다. ChatGPT에게 물어보니, API는 Application Programming Interface의 약자로, 소프트웨어 애플리케이션 간 상호작용을 가능하게 하는 규칙과 도구의 집합을 의미한다고 한다.비전공자가 이해할수 있도록 조금 더 쉽게 설명한다면, API는 서로 다른 소프트웨어가 데이터를 주고받을 수 있도록 설계된 소통의 다리라고 이해할수 있다.
API를 더욱 자세히 이해하기위해 점원이 요리사와 고객을 연결하는 과정을 떠올려 볼수 있다.
2025년 새해를 맞아 가족과 함께 식당에 갔다고 가정해보자.
1. 식당에 들어가면 점원이 예약을 확인 후 자리를 안내하고 메뉴판을 가져다준다.
2. 메뉴판을 보고 점원에게 먹고 싶은 메뉴를 주문한다.
3. 점원은 요리사에게 주문을 전달한다.
4. 30분 후, 점원이 요리사가 완성한 음식을 가져다준다.
이 간단한 이야기를 이해했다면 API의 개념을 충분히 이해 할수 있다.
식당의 예시에서 보았듯이, API는 서로 다른 소프트웨어(고객과 요리사)가 데이터를 주고받을 수 있도록 돕는 소통의 다리(점원)다. API 덕분에 클라이언트(사용자)와 서버(데이터 제공자)는 정보를 원활히 주고받으며, 다양한 애플리케이션 간의 연결과 협력이 가능해진다.
API 문서 이해하기
API에 대한 정의를 이해하였다면, PM/기획자로써 이해해야할 API에 대한 개념을 구체화하고 실전까지 도전해보자
식당에서 가장 중요한 것은 메뉴와 주문 방식이다. 즉 손님이 어떠한 메뉴를, 어떻게 주문하는지에 대한 설명이 있어야 고객이 주문할 수 있다. 식당에서 이러한 설명을 제공하는 것이 메뉴판이라면, API에서는 API 문서가 그 역할을 한다. PM/기획자로 근무하면서 API 문서를 이해할수 있다면 개발자와의 소통을 원활하게 진행할수 있다.
오늘 같이 읽어볼 API 문서는 네이버에서 제공하는 OPEN API의 문서다. (나중에 실전연습까지 할 문서니 꼼꼼히 읽어보자).
문서 링크 : https://developers.naver.com/docs/serviceapi/search/book/book.md#%EC%B1%85
본격적으로 API 문서를 읽어보기에 앞서, API가 어떤 구성 요소로 이루어져 있는지 먼저 살펴보자. 앞서 다룬 식당 예시를 활용한다면, 각 구성 요소가 실제로 어떤 역할을 하는지 쉽게 이해할 수 있다.
API 문서 구조개요
API 문서는 해당 API가 해결할 수 있는 문제와 제공하는 기능에 대한 기본적인 설명으로 시작된다. 이번에 다룰 검색 API는 네이버 검색 결과 중 책에 대한 데이터를 제공하는 API다.
검색 > 책 - Search API (개요)"책 검색 API는 RESTful API를 통해 검색 결과를 반환하고 있으며, 그 결과는 XML 혹은 JSON 형식으로 반환한다. API 호출시는 검색 조건을 Query String으로 전달하고, 하루 호출 한도는 25,000회이다."
개발 지식이 부족한 분들이라면, 위 문장에서 낯선 용어들이 등장했을 것이다. RESTful API, XML, JSON, Query String 등 개발과 관련된 단어들이 포함되어 있다. 이 단어들에 대한 자세한 설명은 뒤에서 다루겠지만, 우선 RESTful API라는 개념부터 살펴보자.
RESTful API는 데이터를 요청하고 응답받는 방식 중 하나로, 가장 널리 사용되는 표준 방식이다. RESTful API의 경우, HTTP라른 프로토콜에 따라, 정해진 데이터 형식(XML 또는 JSON)에 따라 요청받은 데이터를 반환하는 방식으로 데이터를 주고받는 구조를 표준화해 효율성과 일관성을 제공한다.
데이터를 요청하는 방식은 그 이외에도 여러 방식이 있으며, 궁금하다면 이전 글을 한번 읽어보시기를 추천한다. (비전공자 PM이 설명하는 API)
인증 및 보안
네이버 OPEN API에서는 인증 및 보안 관련 부분을 사전 준비 사항으로 전달하고 있다. 복잡한 인증 및 보안의 과정을 식당의 예시로 비유하면, "직원은 식당 입구에서 손님에 대한 예약(인증)을 확인하고 테이블로 안내받습니다."로 이해할수 있다.
API를 사용하기 위해서는 제공하는 서버에 등록을 해야하고 그에 따른 아이디와 시크릿을 발급받아야한다. 맛집으로 유명한 식당을 방문할때 이름과 전화번호를 알려주고 자리를 예약하는 것과 매우 유사하다. 이를 통해 식당 (서버)은 예약한 손님(클라이언트)이 방문시 예약자와 동일한 사람인지 확인할수 있다.
요청 방법
요청 방법이란 API를 요청하기 위해 필요한 정보이다. 즉 식당에서 메뉴를 주문하는 방법과 유사하게 API 호출을 하기 위해서는 API 문서에 명시한 요청 방법을 따라야한다.API에서의 요청 방법은 프로토콜, 요청 URL, HTTP 메서드, 반환 형식으로 구성되며, 이들을 하나씩 알아가보자.
API 요청 방법을 이해하기 위해, 식당에서 점원에게 통해 주문하는 상황으로 이해하면 직관적으로 이해할수 있다.
1. 프로토콜 : 안전한 주문 전달
• 설명: 프로토콜은 데이터를 주고받는 방식으로, HTTP는 데이터를 주고받는 방식, HTTPS는 데이터를 암호화하여 더 안전하게 전달하는 방식이 있다.
• 비유: 테이블에 설치된 점원을 사용해 주문하는 상황을 떠올려 보세요. 점원은 손님의 주문 정보를 요리사와 공유하며, 같은 식당에 있는 다른 손님들은 해당 주문 내용을 알 수 없습니다.
2. 요청 URL : 무엇을 요청할지 지정
• 설명: API 호출을 위한 고유 경로로, 특정 데이터나 서비스를 요청하는 주소입니다.
• 예시 점원에게 “김치찌개” 메뉴를 이야기하면, 요리사는 점원을 통해 이 주문이 무엇을 요청하는지 정확히 알 수 있습니다. 요청 URL은 이러한 과정을 통해 서버가 요청한 데이터의 정확한 내용을 파악할 수 있도록 합니다.
3. HTTP 메서드 : 요청의 목적 정의
• 설명: API 요청의 목적을 정의하며, GET, POST, PUT, DELETE 등의 방식으로 요청을 전달합니다.
• 예시 :
• GET: 메뉴를 가져오기 → 키오스크에서 “김치찌개”를 주문.
• DELETE: 기존 주문 취소 → 이미 주문한 “김치찌개”를 취소하기.
4. 반환 형식 : 데이터 제공 방식 결정
• 설명: 요청한 데이터(메뉴)가 어떤 형식으로 반환되는지를 나타냅니다.
• 비유: 점원에게 메뉴를 주문시 자리에서 먹고갈지, 테이크아웃하여 가져갈지 결정할수 있습니다.
즉, 손님(클라이언트)이 점원(API)를 통해 메뉴를 주문(요청 URL)하면, 주문이 요리사(서버)에게 안전하게 전달되며(프로토콜), 요리사가 이 요청의 목적(HTTP 메서드)을 확인한 뒤, 요청한 메뉴를 접시에 담아 제공하거나(XML), 포장 용기에 담아 반환(JSON)합니다.
요청 매개변수
API에서 요청 매개변수는 API 요청에 필요한 입력 값을 의미합니다.
식당에서 주문할 때 메뉴명을 반드시 알려줘야 하듯이, API 요청에서도 필수 매개변수가 필요합니다. 반면, 손님의 기호에 따라 사리를 추가하거나 맵기를 조절하듯이, API 요청에는 선택적 매개변수도 존재합니다.
이러한 선택적 매개변수를 사용할 때 가장 일반적인 방식이 Query String입니다. Query String은 요청 URL의 끝에 추가되는 파라미터로, 데이터를 필터링하거나 조건을 지정하는 데 사용됩니다.
예시: https://api.example.com/search?query=김치찌개&사리=라면&추가=김치
즉, API 요청 매개변수는 데이터를 요청하고, 조건을 세부적으로 지정하는 데 사용되며, Query String은 이를 효율적으로 처리하고 필요한 정보를 필터링할 수 있도록 돕는 도구입니다.
응답 형식
응답 형식은 우리가 요청한 응답 방식(XML 혹은 JSON)에 따라, 반환하는 결과를 의미합니다.
PM/기획자로 근무하며, 비전공자가 XML과 JSON 형식을 깊이 이해하기에는 현실적으로 어렵습니다. 다만, 실무의 관점에서는 둘의 핵심 차이점을 이해한다면 우리의 목적인 개발자와의 원활한 소통을 위해는 활용할수 있습니다.
XML과 JSON의 가장 큰 차이점:
• XML: 계층 구조를 태그로 표현해 데이터를 명확히 구조화할 수 있지만, 태그가 많아질수록 코드가 길어지고 복잡해진다.
• JSON: 데이터를 키-값 쌍으로 표현하여 간단하고 직관적이지만, 계층 표현이 필요한 복잡한 데이터 구조에서는 가독성이 떨어질 수 있다.
상태 코드
상태코드는 결과를 요청했을때, 반환하는 상태를 의미합니다. 정확하게는 해당 요청이 성공했는지, 실패하였는지에 대한 여부를 확인할수 있는 코드가 상태 코드입니다.
네이버에서는 오류 코드를 줄때, HTTP 상태코드로 400번을 보내주고 있습니다. 이는 해당 요청이 잘못되었을 경우로, 이러한 응답값을 받는다면 위에 요청 매개변수를 다시 확인하여야합니다.
제한 및 정책
API를 운영하다보면 기획자로 준비해야하는 정책 중 하나가 호출수에 대한 제한이다. 무제한 호출은 서버 비용에 대한 증가와 운영에 대한 부담 증가로 이어질수 있어 적절한 호출수 제한이 필요합니다. PM/기획자로 근무하며, API에 대한 정책을 결정해야한다면, 이 호출수에 대한 고민이 필요합니다.
글을 마치며,
기획자가 공부하는 API Part.1에 대한 내용은 API에 대한 정의와 API 문서에 대한 이해에 대해 주로 다루었습니다. 제공하는 서비스 별로 일부 더 공부가 필요한 부분은 있을수 있지만, PM으로 근무하면서 이 정도의 개념을 숙지하고 있다면, API 문서를 본다고 하더라도 70%~80%의 개념은 이해할수 있습니다.
다음 글은 오늘 배운 OPEN API를 실제 구현하는 방법에 대해 소개하려합니다. 이를 통해 API가 실무에서 어떤 방식으로 작동하는지 이해하고, 실무에서 개발자들과 원활하게 소통할수 있도록 설명하려고 합니다.
