Python Flask로 첫 API 서버 만들기

API 서버는 무엇을 하는가

API 서버는 웹 브라우저, 모바일 앱, 다른 서버 등의 요청을 받아 필요한 데이터를 정해진 형식으로 돌려주는 프로그램입니다. 예를 들어 클라이언트가 /api/hello 주소로 GET 요청을 보내면 서버는 인사말을 JSON 형태로 응답할 수 있습니다. 화면을 직접 만드는 일반 웹 페이지와 달리, API 서버는 주로 데이터와 처리 결과를 전달한다는 점이 특징입니다.

API 학습방법의 첫 단계는 HTTP 요청과 응답의 흐름을 이해하는 것입니다. 클라이언트는 URL과 요청 방식(GET, POST 등)을 보내고, 서버는 본문 데이터와 상태 코드(200, 404 등)를 응답합니다. Flask는 이 흐름을 짧은 Python 코드로 구현할 수 있게 돕는 웹 프레임워크입니다.

개발 환경 준비하기

먼저 Python 3가 설치되어 있는지 터미널에서 확인합니다.

python --version

프로젝트별 패키지 충돌을 줄이려면 가상 환경을 사용하는 것이 좋습니다. 원하는 폴더에서 다음 명령을 실행합니다.

python -m venv venv

Windows에서는 venv\Scripts\activate, macOS와 Linux에서는 source venv/bin/activate 명령으로 가상 환경을 활성화합니다. 이후 Flask를 설치합니다.

pip install flask

이 과정을 거치면 다른 프로젝트에 설치된 라이브러리와 분리하여 실습할 수 있습니다. 처음에는 명령어를 외우기보다, 가상 환경이 프로젝트의 독립적인 Python 작업 공간이라는 원리를 이해하면 충분합니다.

첫 번째 Flask API 작성하기

프로젝트 폴더에 app.py 파일을 만들고 아래 코드를 작성합니다.

from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/api/hello', methods=['GET'])
def hello():
return jsonify({
'message': '안녕하세요, Flask API입니다.'
})

if __name__ == '__main__':
app.run(debug=True)

Flask(__name__)은 Flask 애플리케이션 객체를 만드는 코드입니다. @app.route는 특정 URL 요청을 어떤 함수가 처리할지 연결하는 장식자입니다. 여기서는 GET /api/hello 요청이 들어오면 hello 함수가 실행됩니다.

jsonify는 Python 딕셔너리를 JSON 응답으로 바꾸고 적절한 Content-Type도 설정합니다. API에서는 문자열을 직접 반환할 수도 있지만, 구조화된 데이터를 주고받기 위해 JSON을 사용하는 경우가 많습니다.

서버 실행과 응답 확인

터미널에서 다음 명령으로 서버를 실행합니다.

python app.py

기본 설정이라면 http://127.0.0.1:5000 에서 서버가 실행됩니다. 브라우저 주소창이나 API 테스트 도구에서 http://127.0.0.1:5000/api/hello 를 열어 보세요. 다음과 비슷한 응답을 확인할 수 있습니다.

{"message":"안녕하세요, Flask API입니다."}

127.0.0.1은 현재 사용하는 컴퓨터를 뜻하는 로컬 주소입니다. 즉, 지금 만든 서버는 인터넷에 공개된 것이 아니라 내 컴퓨터에서만 실행되는 개발용 서버입니다. debug=True는 코드를 수정했을 때 서버를 자동으로 다시 시작하고 오류 화면을 자세히 보여 줍니다. 다만 운영 환경에서는 보안상 debug 모드를 켜면 안 됩니다.

상태 코드와 오류 응답 추가하기

API는 성공한 경우뿐 아니라 요청이 잘못된 경우도 일관된 형식으로 알려야 합니다. 예를 들어 존재하지 않는 사용자 정보를 요청했을 때는 404 상태 코드를 반환할 수 있습니다.

from flask import jsonify

@app.route('/api/users/<int:user_id>', methods=['GET'])
def get_user(user_id):
if user_id != 1:
return jsonify({'error': '사용자를 찾을 수 없습니다.'}), 404
return jsonify({'id': 1, 'name': 'Kim'}), 200

<int:user_id> 부분은 URL에서 숫자를 받아 함수의 user_id 변수로 전달합니다. 반환값 뒤에 , 404처럼 상태 코드를 함께 작성할 수 있습니다. 200은 요청 성공, 404는 요청한 자원이 없음을 의미합니다. 이러한 규칙은 클라이언트가 결과를 정확히 판단하는 데 도움을 줍니다.

다음 학습 순서

첫 API가 동작했다면 POST 요청으로 데이터를 받는 방법을 이어서 학습하는 것이 좋습니다. request.get_json()으로 JSON 본문을 읽고, 입력값이 비어 있는지 검사한 뒤 201 Created 같은 상태 코드를 응답하는 연습을 해 보세요. 그다음에는 데이터를 메모리가 아닌 SQLite 같은 데이터베이스에 저장하고, 환경 변수로 비밀값을 관리하는 단계로 확장할 수 있습니다.

기초 단계에서는 기능을 많이 넣기보다 요청 URL, HTTP 메서드, JSON, 상태 코드의 관계를 직접 바꿔 보며 확인하는 방법이 효과적입니다. 터미널 로그와 응답 내용을 함께 관찰하면 API 서버가 요청을 처리하는 원리를 더 분명하게 이해할 수 있습니다.

자주 묻는 질문