API를 배우기 전 알아야 할 IT 기초 용어

API는 프로그램끼리 대화하는 창구입니다

API(Application Programming Interface)는 한 프로그램이 다른 프로그램의 기능이나 데이터를 이용할 수 있도록 정해 둔 규칙입니다. 예를 들어 지도 앱이 현재 날씨를 표시할 때, 날씨 서비스의 API에 요청을 보내고 결과를 받아 화면에 보여줄 수 있습니다. 이때 중요한 점은 API가 단순히 ‘데이터를 받는 주소’만은 아니라는 것입니다. 어떤 주소로 요청할지, 어떤 정보를 함께 보낼지, 결과가 어떤 형식으로 돌아오는지까지 포함한 약속입니다.

API를 이해하려면 먼저 웹에서 정보가 오가는 원리를 익히는 것이 좋습니다. 사용자가 브라우저나 앱에서 요청을 보내면 서버가 이를 처리하고 응답을 돌려주는 흐름이 API의 기본 구조입니다.

클라이언트와 서버의 역할

클라이언트(client)는 서비스를 요청하는 쪽입니다. 웹 브라우저, 모바일 앱, 또는 파이썬으로 작성한 프로그램이 클라이언트가 될 수 있습니다. 서버(server)는 요청을 받아 필요한 작업을 수행한 뒤 결과를 반환하는 쪽입니다. 로그인 정보를 확인하거나, 상품 목록을 조회하거나, 데이터를 저장하는 작업은 보통 서버에서 처리합니다.

예를 들어 파이썬 코드에서 특정 API를 호출한다면 파이썬 프로그램은 클라이언트입니다. 서버는 요청을 받았는지, 필요한 권한이 있는지 확인한 뒤 JSON 같은 형식으로 결과를 응답합니다. 이 역할 구분을 이해하면 오류가 발생했을 때 내 코드 문제인지, 서버 응답 문제인지 판단하기 쉬워집니다.

요청과 응답: HTTP의 기본 원리

웹 API 대부분은 HTTP(HyperText Transfer Protocol)라는 통신 규칙을 사용합니다. HTTP 요청에는 보통 URL, 메서드, 헤더, 본문이 포함됩니다. URL은 요청할 대상의 위치를 나타내고, 메서드는 수행하려는 작업의 종류를 표현합니다.

대표적인 메서드는 GET, POST, PUT 또는 PATCH, DELETE입니다. GET은 데이터를 조회할 때, POST는 새 데이터를 만들 때 주로 사용합니다. PUT 또는 PATCH는 기존 데이터를 수정할 때, DELETE는 데이터를 삭제할 때 활용합니다. 실제 서비스마다 세부 규칙은 다를 수 있으므로 API 문서의 설명을 확인해야 합니다.

응답에는 상태 코드가 포함됩니다. 200은 일반적으로 요청 성공, 201은 생성 성공을 뜻합니다. 400번대 코드는 요청 내용이나 인증에 문제가 있는 경우가 많고, 500번대 코드는 주로 서버 내부 오류를 의미합니다. 상태 코드와 응답 메시지를 함께 읽는 습관은 API 학습의 중요한 기초입니다.

URL, 엔드포인트, 파라미터 구분하기

URL은 웹 자원의 위치를 나타내는 주소입니다. 그중 API가 제공하는 특정 기능의 주소를 엔드포인트(endpoint)라고 부릅니다. 예를 들어 /users는 사용자 목록을 다루는 엔드포인트가 될 수 있고, /users/42는 42번 사용자 한 명을 가리킬 수 있습니다.

파라미터(parameter)는 서버에 조건이나 추가 정보를 전달하는 값입니다. 주소 경로에 포함되는 경로 파라미터와, ?page=2처럼 URL 뒤에 붙는 쿼리 파라미터가 있습니다. 검색어, 페이지 번호, 정렬 방식은 쿼리 파라미터로 전달되는 경우가 많습니다. 비밀번호나 토큰처럼 민감한 정보는 URL에 노출하지 않고 보통 헤더나 요청 본문으로 전달합니다.

JSON과 데이터베이스의 관계

JSON(JavaScript Object Notation)은 API가 데이터를 주고받을 때 널리 쓰는 텍스트 형식입니다. 키와 값의 쌍으로 정보를 표현하며, 파이썬의 딕셔너리와 형태가 비슷합니다. 예를 들어 이름, 이메일, 가입일 같은 사용자 정보가 JSON 객체로 응답될 수 있습니다.

서버는 이런 데이터를 대개 데이터베이스(database)에 저장합니다. 데이터베이스는 정보를 체계적으로 보관하고 조회하는 시스템입니다. API는 클라이언트가 데이터베이스에 직접 접근하지 않도록 중간에서 권한을 확인하고, 필요한 데이터만 가공해 전달합니다. 따라서 API는 데이터베이스 그 자체가 아니라 데이터를 안전하게 다루기 위한 인터페이스라는 점을 구분해야 합니다.

인증, 권한, 보안 용어

인증(authentication)은 ‘누구인지 확인하는 과정’이고, 권한 부여(authorization)는 ‘무엇을 할 수 있는지 판단하는 과정’입니다. 로그인 후 발급받는 API 키나 액세스 토큰은 요청한 프로그램 또는 사용자를 식별하는 데 사용됩니다. 토큰은 보통 Authorization 헤더에 담아 보냅니다.

API 키와 토큰은 비밀번호처럼 다뤄야 합니다. 깃 저장소에 그대로 올리거나, 브라우저용 코드에 중요한 비밀 키를 넣으면 유출 위험이 있습니다. 학습 중에도 환경 변수나 별도 설정 파일을 활용해 키를 코드와 분리하는 습관을 들이는 것이 좋습니다. 또한 HTTPS는 통신 내용을 암호화하는 방식이므로, 실제 서비스 API는 가능한 한 HTTPS 주소를 사용해야 합니다.

초보자를 위한 API 학습방법

API 학습은 용어를 한 번에 외우기보다 요청과 응답을 직접 확인하며 진행하는 방법이 효과적입니다. 먼저 공개 API 문서에서 엔드포인트 하나를 고르고, 요청 URL·필수 파라미터·응답 예시·인증 방식 순서로 읽어 보세요. 그다음 브라우저, API 테스트 도구 또는 파이썬의 requests 라이브러리로 GET 요청부터 실행해 보면 흐름이 보입니다.

이후에는 응답 JSON에서 원하는 값을 꺼내 화면이나 콘솔에 출력하고, 파라미터를 바꿔 결과가 어떻게 달라지는지 비교해 보세요. 오류가 나면 상태 코드, 응답 본문, 요청에 보낸 값의 철자를 차례로 확인합니다. 작은 조회 기능을 안정적으로 구현한 뒤 POST 요청, 인증, 예외 처리로 범위를 넓히면 API의 원리를 더 단단하게 이해할 수 있습니다.

자주 묻는 질문