728x90

API가 뭐길래? 모든 개발자들이 말하는 그것

안녕하세요 여러분! 오늘은 개발 세계에서 정말 많이 들리는 단어, 바로 'API'에 대해 알아볼게요.

개발자가 아니더라도 한 번쯤은 들어봤을 이 단어, 대체 뭘까요? 같이 쉽게 알아봐요!

API란 무엇인가?

오늘 공부할 개발 지식은 API에요. API는 Application Programming Interface의 약자로, 소프트웨어 애플리케이션 간 상호작용을 가능하게 하는 규칙과 도구의 집합을 의미한다고 해요.

비전공자가 이해할 수 있도록 조금 더 쉽게 설명한다면, API는 서로 다른 소프트웨어가 데이터를 주고받을 수 있도록 설계된 소통의 다리라고 이해할 수 있어요.

API 이해하기: 식당 예시로 알아보기

API를 더욱 자세히 이해하기 위해 점원이 요리사와 고객을 연결하는 과정을 떠올려 볼게요.

2025년 새해를 맞아 가족과 함께 식당에 갔다고 가정해봐요.

식당에 들어가면 점원이 예약을 확인 후 자리를 안내하고 메뉴판을 가져다줘요.
메뉴판을 보고 점원에게 먹고 싶은 메뉴를 주문해요.
점원은 요리사에게 주문을 전달해요.
30분 후, 점원이 요리사가 완성한 음식을 가져다줘요.

이 간단한 이야기를 이해했다면 API의 개념을 충분히 이해할 수 있어요!

식당의 예시에서 보았듯이, API는 서로 다른 소프트웨어(고객과 요리사)가 데이터를 주고받을 수 있도록 돕는 소통의 다리(점원)에요. API 덕분에 클라이언트(사용자)와 서버(데이터 제공자)는 정보를 원활히 주고받으며, 다양한 애플리케이션 간의 연결과 협력이 가능해져요.

API 문서 이해하기

API에 대한 정의를 이해했다면, 이제 API 문서에 대한 개념을 구체화하고 실전에 도전해볼게요!

식당에서 가장 중요한 것은 메뉴와 주문 방식이에요. 즉 손님이 어떠한 메뉴를, 어떻게 주문하는지에 대한 설명이 있어야 고객이 주문할 수 있죠. 식당에서 이러한 설명을 제공하는 것이 메뉴판이라면, API에서는 API 문서가 그 역할을 해요.

API의 주요 구성 요소

1. 개요

API 문서는 해당 API가 해결할 수 있는 문제와 제공하는 기능에 대한 기본적인 설명으로 시작돼요. 예를 들어, 네이버 검색 API는 네이버 검색 결과 중 책에 대한 데이터를 제공하는 API예요.

"책 검색 API는 RESTful API를 통해 검색 결과를 반환하고 있으며, 그 결과는 XML 혹은 JSON 형식으로 반환해요. API 호출시는 검색 조건을 Query String으로 전달하고, 하루 호출 한도는 25,000회에요."

RESTful API는 데이터를 요청하고 응답받는 방식 중 하나로, 가장 널리 사용되는 표준 방식이에요. HTTP라는 프로토콜에 따라, 정해진 데이터 형식(XML 또는 JSON)에 따라 요청받은 데이터를 반환하는 방식으로 데이터를 주고받는 구조를 표준화해 효율성과 일관성을 제공해요.

2. 인증 및 보안

네이버 OPEN API에서는 인증 및 보안 관련 부분을 사전 준비 사항으로 전달하고 있어요. 복잡한 인증 및 보안의 과정을 식당의 예시로 비유하면, "직원은 식당 입구에서 손님에 대한 예약(인증)을 확인하고 테이블로 안내받습니다."로 이해할 수 있어요. 문서 링크 : https://developers.naver.com/docs/serviceapi/search/book/book.md#%EC%B1%85

API를 사용하기 위해서는 제공하는 서버에 등록을 해야하고 그에 따른 아이디와 시크릿을 발급받아야 해요. 맛집으로 유명한 식당을 방문할 때 이름과 전화번호를 알려주고 자리를 예약하는 것과 매우 유사해요. 이를 통해 식당(서버)은 예약한 손님(클라이언트)이 방문 시 예약자와 동일한 사람인지 확인할 수 있어요.

3. 요청 방법

요청 방법이란 API를 요청하기 위해 필요한 정보예요.

즉 식당에서 메뉴를 주문하는 방법과 유사하게 API 호출을 하기 위해서는 API 문서에 명시한 요청 방법을 따라야 해요. API에서의 요청 방법은 프로토콜, 요청 URL, HTTP 메서드, 반환 형식으로 구성되며, 이들을 하나씩 알아볼게요:

a) 프로토콜: 안전한 주문 전달

프로토콜은 데이터를 주고받는 방식으로, HTTP는 기본적인 데이터 전송 방식, HTTPS는 데이터를 암호화하여 더 안전하게 전달하는 방식이 있어요.

비유하자면 테이블에 설치된 점원 호출 버튼을 사용해 주문하는 상황을 떠올려 보세요. 점원은 손님의 주문 정보를 요리사와 공유하며, 같은 식당에 있는 다른 손님들은 해당 주문 내용을 알 수 없어요.

b) 요청 URL: 무엇을 요청할지 지정

요청 URL은 API 호출을 위한 고유 경로로, 특정 데이터나 서비스를 요청하는 주소예요.

예를 들어, 점원에게 "김치찌개" 메뉴를 이야기하면, 요리사는 점원을 통해 이 주문이 무엇을 요청하는지 정확히 알 수 있어요. 요청 URL은 이러한 과정을 통해 서버가 요청한 데이터의 정확한 내용을 파악할 수 있도록 해요.

c) HTTP 메서드: 요청의 목적 정의

HTTP 메서드는 API 요청의 목적을 정의하며, GET, POST, PUT, DELETE 등의 방식으로 요청을 전달해요.

예시:

GET: 메뉴를 가져오기 → 키오스크에서 "김치찌개"를 주문
DELETE: 기존 주문 취소 → 이미 주문한 "김치찌개"를 취소하기

d) 반환 형식: 데이터 제공 방식 결정

반환 형식은 요청한 데이터(메뉴)가 어떤 형식으로 반환되는지를 나타내요.

비유하자면 점원에게 메뉴를 주문 시 자리에서 먹고 갈지, 테이크아웃하여 가져갈지 결정할 수 있어요.

즉, 손님(클라이언트)이 점원(API)를 통해 메뉴를 주문(요청 URL)하면, 주문이 요리사(서버)에게 안전하게 전달되며(프로토콜), 요리사가 이 요청의 목적(HTTP 메서드)을 확인한 뒤, 요청한 메뉴를 접시에 담아 제공하거나(XML), 포장 용기에 담아 반환(JSON)해요.

4. 요청 매개변수

API에서 요청 매개변수는 API 요청에 필요한 입력 값을 의미해요.

식당에서 주문할 때 메뉴명을 반드시 알려줘야 하듯이, API 요청에서도 필수 매개변수가 필요해요. 반면, 손님의 기호에 따라 사리를 추가하거나 맵기를 조절하듯이, API 요청에는 선택적 매개변수도 존재해요.

이러한 선택적 매개변수를 사용할 때 가장 일반적인 방식이 Query String이에요. Query String은 요청 URL의 끝에 추가되는 파라미터로, 데이터를 필터링하거나 조건을 지정하는 데 사용돼요.

예시: https://api.example.com/search?query=김치찌개&사리=라면&추가=김치

즉, API 요청 매개변수는 데이터를 요청하고, 조건을 세부적으로 지정하는 데 사용되며, Query String은 이를 효율적으로 처리하고 필요한 정보를 필터링할 수 있도록 돕는 도구예요.

5. 응답 형식

응답 형식은 우리가 요청한 응답 방식(XML 혹은 JSON)에 따라, 반환하는 결과를 의미해요.

XML과 JSON의 가장 큰 차이점:

XML: 계층 구조를 태그로 표현해 데이터를 명확히 구조화할 수 있지만, 태그가 많아질수록 코드가 길어지고 복잡해져요.
JSON: 데이터를 키-값 쌍으로 표현하여 간단하고 직관적이지만, 계층 표현이 필요한 복잡한 데이터 구조에서는 가독성이 떨어질 수 있어요.

6. 상태 코드

상태 코드는 결과를 요청했을 때, 반환하는 상태를 의미해요. 정확하게는 해당 요청이 성공했는지, 실패했는지에 대한 여부를 확인할 수 있는 코드가 상태 코드예요.

네이버에서는 오류 코드를 줄 때, HTTP 상태 코드로 400번을 보내주고 있어요. 이는 해당 요청이 잘못되었을 경우로, 이러한 응답값을 받는다면 요청 매개변수를 다시 확인해야 해요.

7. 제한 및 정책

API를 운영하다 보면 호출 수에 대한 제한이 필요해요. 무제한 호출은 서버 비용에 대한 증가와 운영에 대한 부담 증가로 이어질 수 있어 적절한 호출 수 제한이 필요해요.

마무리

API에 대한 정의와 API 문서 이해에 대해 주로 다뤘어요. 제공하는 서비스별로 일부 더 공부가 필요한 부분은 있을 수 있지만, 이 정도의 개념을 숙지하고 있다면, API 문서를 본다고 하더라도 70%~80%의 개념은 이해할 수 있어요!

API가 실무에서 어떤 방식으로 작동하는지 이해하고, 실무에서 개발자들과 원활하게 소통할 수 있도록 이 내용이 도움이 됐으면 좋겠어요~