API란 무엇인가요?
API는 "Application Programming Interface"의 약자로, 서로 다른 소프트웨어가 대화할 수 있도록 돕는 연결 통로라고 생각하시면 됩니다. 예를 들어, 우리(클라이언트)가 키움증권(서버)에 주식 주문을 요청하고 그 주문 결과를 받고자 할 때, 그 일련의 과정을 API가 도와주는 역할을 하는 것입니다.
개발환경 구축하기
VSCode 설치
VSCode는 가볍고 다양한 언어를 지원하는 확장 가능한 코드 편집기로, 무료로 다양한 개발 환경을 설정하고 사용할 수 있습니다.
사전 설치 항목 (Python)
VS Code를 설치하기 전 Python 설치가 선행되어야합니다. 설치 가이드는 아래와 같습니다.
1. Python 공식 웹사이트 에 접속하여 OS에 맞는 설치 파일을 다운로드합니다.
2. 설치 파일을 실행합니다.
① Add python.exe to PATH를 체크합니다.
② Install Now를 선택합니다.
3. 설치가 완료되면, 명령어 프롬프트 또는 터미널을 열고 Python이 제대로 설치되었는지 확인합니다.
- 소스코드
Shell
python --version
- 실행결과
4. pip 업데이트(선택 사항)
- pip는 Python 패키지 관리자로, 설치된 후 최신 버전으로 업데이트 하는 것이 좋습니다.
Shell
python -m pip install --upgrade pip
VSCode 설치 방법
1. VSCode 웹사이트로 이동: VSCode 홈페이지에 접속하여 OS에 맞는 설치 파일을 다운로드하여 설치합니다.
2. 설치 파일을 실행 후 아래 사진과 같이 동일하게 진행합니다.
3. Python Extension 설치
① 좌측 상단 Extension 아이콘을 선택합니다.
② 입력창에 Python을 입력하여 extension 목록을 조회합니다.
③ Python extension이 조회가 되면 install 버튼을 눌러 설치합니다.
새프로젝트 생성 및 샘플 코드 실행
1. 프로젝트 폴더 생성 및 열기: 원하는 위치에 폴더 생성 후 VS Code에서 프로젝트 폴더를 엽니다.
① Open Folder 버튼을 클릭합니다.
② 새로 생성한 프로젝트 폴더를 선택합니다.
2. 샘플 코드 작성: 새 파일(sample.py)을 생성하고 코드 작성 환경을 구성합니다.
① 새파일 만들기 아이콘을 클릭 후 sample.py 입력하여 샘플파일을 만듭니다.
3. Python Interpreter 선택: Python을 실행시키기 위한 가상환경을 선택합니다.
① Ctrl+Shift+P -> Python: Select Interpreter 입력 후 선택합니다.
② 로컬 PC에 설치된 python 환경들 중 하나를 선택합니다.
4. 라이브러리 설치: pip install을 통해 requests 라이브러리를 설치합니다.
① 상단 Terminal 메뉴를 클릭합니다.
② New Terminal를 통해 새 터미널을 생성합니다.
③ 화면 하단 터미널이 생성 됐다면 pip install requests를 입력합니다.
④ 'Successfully installed requests' 문구가 나왔다면 Requests 라이브러리가 정상적으로 설치가 완료되었습니다.
5. 예제 소스 입력 후 실행: 예제 소스 입력 후 Run Python File in Terminal 선택 또는 상단 실행 버튼 클릭합니다.
예제소스
Python
import requests
response = requests.get("https://www.python.org") # Python 공식 사이트 간단한 GET 요청
print("응답 상태 코드:", response.status_code)
실행결과
Anaconda 설치
Anaconda는 가상 환경 및 라이브러리 관리에 뛰어나며, 데이터 과학과 머신러닝 프로젝트에 최적화된 환경을 제공 합니다.
설치 방법
1. Anaconda 웹사이트로 이동: Anaconda 공식 웹사이트에 접속합니다.
① Skip registration을 클릭합니다.
① Skip registration을 클릭합니다.
2. 설치 파일을 실행 후 아래 사진과 같이 동일하게 진행합니다.
3. Anaconda를 실행합니다.
4. Anaconda에서 Python을 실행할 수 있는 IDE 또는 edit tool을 선택하여 실행합니다.
① Home 메뉴로 이동합니다.
② Jupyter Notebook 서비스의 Launch 버튼을 누릅니다.
5. Jupyter에서 프로젝트 폴더와 파일을 생성합니다.
① New 버튼을 통해 sample 폴더를 임의의 경로에 생성합니다.
② 생성한 sample 폴더에 들어가서 New 버튼으로 Python 파일을 생성합니다.
6. 예제 소스 입력 후 실행: 예제 소스 입력 후 상단 실행 버튼 클릭합니다.
① 새로 생성한 sample.py 파일에 들어가서 예제 소스를 입력합니다.
② 상단 실행 버튼을 클릭하여 예제소스의 실행 결과를 확인합니다.
REST API 이해하기
안녕하세요! 이번 문서에서는 API와 관련된 기본 개념과 REST API를 사용하여 주식 매매를 요청하는 방법을 간단하게 설명 드리겠습니다. 이 설명은 REST API를 처음 접하시는 분들도 쉽게 이해할 수 있도록 준비했습니다.
REST API란 무엇인가요?
REST API는 API의 한 종류로, "Representational State Transfer"의 약자입니다. 데이터를 주고받는 방식 중 하나로, URL(주소)과 HTTP 메서드(GET, POST 등)을 사용하여 서버와 통신합니다. 쉽게 말하자면, REST API는 인터넷을 통해 요청을 보내고 응답을 받는 "규칙"입니다. 예를 들어 우리가 인터넷 브라우저에서 특정 웹페이지를 열 때, 브라우저는 URL을 통해 요청을 보내고 해당 데이터를 받아옵니다. REST API도 이와 비슷하게 프로그램이 서버에 요청을 보내고 데이터를 받아오는 방식입니다.
REST API의 기본 동작 방식
- URL(주소): 데이터를 요청하거나 보낼 위치를 나타냅니다. 예: https://api.kiwoom.com/api/dostk/ordr로 보냅니다.
-
HTTP 메서드: 서버와 어떤 작업을 할지 정하는 방식입니다.
- GET: 데이터를 가져오는 요청
- POST: 새로운 데이터를 보내는 요청
- PUT: 데이터를 수정하는 요청
- DELETE: 데이터를 삭제하는 요청
REST API는 간단하고 직관적입니다. REST 방식을 사용하지 않는다면, 데이터를 주고받기 위해 복잡한 프로토콜이나 별도의 파일 변환 작업이 필요할 수 있습니다. 파일 저장 및 처리 과정에서 시간이 오래 걸리고, 서버와 클라이언트 간에 통신 오류가 발생할 가능성이 높습니다. 반면 REST API를 사용하면 간단한 코드로 데이터를 주고받을 수 있습니다.
Python
headers = {
'Content-Type': 'application/json;charset=UTF-8', # 요청 데이터의 형식
'authorization': f'Bearer {token}', # 인증 토큰
'cont-yn': cont_yn, # 연속조회 여부
'next-key': next_key, # 연속조회 키
'api-id': 'kt10000', # 요청하는 TR 이름
}
REST API는 간단하고 직관적입니다. REST 방식을 사용하지 않는다면, 데이터를 주고받기 위해 복잡한 프로토콜이나 별도의 파일 변환 작업이 필요할 수 있습니다. 파일 저장 및
처리 과정에서 시간이 오래 걸리고, 서버와 클라이언트 간에 통신 오류가 발생할 가능성이 높습니다. 반면 REST API를 사용하면 간단한 코드로 데이터를 주고받을 수
있습니다.
여기서 사용한 requests는 Python의 requests
라이브러리를 이용한 것인데 requests 라이브러리는 REST API와 같은 HTTP 기반의 요청을 쉽게 처리할 수 있도록 도와주는 도구입니다. HTTP 요청(GET, POST
등)을 간단한 코드로 작성할 수 있어 REST API 작업에 자주 사용됩니다. requests를 활용하면, 데이터를 요청하거나 서버에 보낼 때 복잡한 작업을 줄이고 효율적으로
통신할 수 있습니다.
JSON이란?
JSON은 "JavaScript Object Notation"의 약자로, 데이터를 저장하거나 교환할 때 사용하는 매우 간단하고 직관적인 형식입니다. REST API를 통해 데이터를 주고받을 때, 데이터 표현 형식으로 주로 JSON형식을 사용합니다. (cf. JSON 외에도 XML, RSS 등 다양한 표현 형식이 있습니다.)
JSON의 구조는 다음과 같은 기본 요소로 구성됩니다:
- 키(Key)와 값(Value): JSON 데이터는 키와 값으로 이루어진 쌍으로 구성됩니다. 키는 데이터를 설명하는 이름이고, 값은 그 키에 해당하는 데이터를 나타냅니다.
- 데이터 타입: JSON에서 값은 다양한 데이터 타입을 가질 수 있습니다. 문자열, 숫자, 불리언 값, 배열, 객체 등이 포함됩니다. 예를 들어 문자열은 '039490', 숫자는 1, 불리언 값은 true 또는 false로 표현됩니다. 배열은 여러 값을 나열한 형태로, 예를 들어 ["039490", "000660"]처럼 구성할 수 있습니다. 객체는 여러 키-값 쌍으로 구성된 데이터 그룹으로, 예를 들어 { "종목코드": "039490", "주문수량": 1 }와 같은 구조를 가집니다.
- 중첩 구조: JSON은 객체 안에 객체를 포함하거나 배열 안에 객체를 포함하는 등 복잡한 데이터를 표현할 수 있는 유연한 구조를 가지고 있습니다.
아래는 키움증권 주식을 1주 시장가로 매수하기 위한 JSON 데이터 예시입니다:
Python
{
"종목코드": "039490",
"주문수량": 1,
"매매구분": "시장가"
}
이 데이터를 보면, "종목코드"라는 키에는 "039490"이라는 값이 들어 있고, "주문수량"에는 숫자 1이 들어 있습니다. "매매구분"에는 "시장가"라는 문자열이 들어 있습니다.
JSON의 장점은?
JSON은 우선, 사람이 읽기에 매우 쉽습니다. JSON은 직관적인 구조를 가지고 있어서 데이터를 쉽게 이해할 수 있습니다. 또한, 대부분의 프로그래밍 언어에서 JSON을 쉽게
파싱(해석)하고 생성할 수 있어 컴퓨터가 처리하기에도 용이합니다. 게다가 JSON은 널리 사용되는 표준 데이터 형식이기 때문에 다양한 시스템 간에 쉽게 호환됩니다
SON은 API와 데이터 통신을 할 때 중요한 역할을 합니다. REST API를 효과적으로 사용하려면 JSON 형식을 잘 이해하는 것이 큰 도움이 됩니다.
매수주문 따라해보기
이제 API를 사용해 주식을 매수하는 방법을 코드로 나누어 설명드리겠습니다.
요청할 URL 구성
-
URL(주소): 데이터를 요청하거나 보낼 위치를 나타냅니다. 예: https://api.kiwoom.com/api/dostk/ordr
- host = 'https://api.kiwoom.com' # 실전투자 서버
- endpoint = '/api/dostk/ordr' # 매수 주문 API
- url = host + endpoint
Host는 API 서버의 기본 주소로, 요청을 처리하는 서버의 위치를 나타냅니다. 예를 들어, 여기에서는 실전 투자 환경의 API 서버 주소인 https://api.kiwoom.com이 사용됩니다. Endpoint는 API가 제공하는 특정 기능에 접근하기 위한 경로입니다. 매수 주문의 경우 /api/dostk/ordr라는 경로를 사용하여 해당 기능을 호출합니다. Host와 Endpoint를 조합하여 최종적으로 요청할 URL을 구성합니다.
헤더(Header)란?
헤더는 API 요청에 필요한 추가 정보를 담고 있는 부분입니다. 요청을 처리하는 데 필요한 메타데이터나 인증 정보를 포함하며, 서버가 요청을 이해하고 처리할 수 있도록 도와줍니다.
헤더 구성 요소
Python
headers = {
'Content-Type': 'application/json;charset=UTF-8', # 요청 데이터의 형식
'authorization': f'Bearer {token}', # 인증 토큰
'cont-yn': cont_yn, # 연속조회 여부
'next-key': next_key, # 연속조회 키
'api-id': 'kt10000', # 요청하는 TR 이름
}
바디(Body)란?
바디는 API 요청에서 전달할 주요 데이터를 포함하는 부분입니다. 바디에는 매매와 관련된 세부 정보가 JSON 형식으로 포함됩니다.
바디 구성 요소
Python
data = {
'dmst_stex_tp': 'KRX', # 거래소 구분 (예: KRX)
'stk_cd': '039490', # 주문할 종목코드 (키움증권)
'ord_qty': '1', # 주문 수량
'ord_uv': '', # 주문 단가 (시장가 주문은 빈 값)
'trde_tp': '3', # 매매 구분 (3: 시장가 주문)
'cond_uv': '', # 조건 단가 (해당 사항 없으면 빈 값)
}
요청 실행
모든 구성 요소를 준비한 뒤 API 요청을 실행합니다
Python
response = requests.post(url, headers=headers, json=data)
이 코드는 HTTP POST 요청을 통해 데이터를 서버에 전송합니다. 요청에는 서버 주소, 요청 헤더, 그리고 요청 본문이 포함됩니다.
- 1. 요청에 사용되는 url은 서버의 주소로, Host와 Endpoint를 조합하여 만들어집니다. 이 주소는 요청이 어디로 전송될지를 나타냅니다.
- 2. headers는 요청에 포함된 추가 정보로, 데이터의 형식(예: JSON)이나 인증 정보를 전달합니다. 이를 통해 서버는 요청이 올바른 형식으로 전송되었는지 확인할 수 있습니다.
- 3. json은 요청 본문에 포함된 데이터입니다. 주식 주문과 관련된 주요 정보들이 JSON 형식으로 여기에 포함됩니다. 이를 통해 서버는 요청의 내용을 처리하고 필요한 작업을 수행합니다.
- 4. 이 요청이 전송되면 서버는 요청을 처리한 결과를 반환하며, 그 결과는 response 변수에 저장됩니다. 이 변수는 응답 결과의 HTTP 상태코드, 헤더, 본문 데이터를 포함하고 있습니다.
- cf. HTTP(Hypertext Transfer Protocol) 상태코드란?
- 앞서 REST API는 URL과 HTTP 메서드를 사용하여 서버와 통신하는 규칙이라고 서술했었습니다. 이 HTTP 메서드로 요청을 보낼 때 요청이 성공적으로 이루어졌는지, 만일 실패했다면 어떤 이유로 실패했는지를 간단히 나타내는 코드를 HTTP 상태코드라고 합니다. 대표적인 HTTP 상태코드 몇 가지만 참고로 적어드립니다.
- 200(OK): 요청 성공
- 400(Bad Request): 요청의 문법이 잘못되어 서버가 요청을 이해할 수 없음
- 403(Forbidden): 클라이언트가 리소스에 접근할 권리를 갖고 있지 않음
- 404(Not Found): 서버에서 요청받은 리소스를 찾을 수 없음
응답 처리
응답 결과를 확인하는 코드입니다:
Python
print('Code:', response.status_code) # HTTP 상태 코드 출력
print('Header:', json.dumps(response.headers, indent=4, ensure_ascii=False)) # 응답 헤더 출력
print('Body:', json.dumps(response.json(), indent=4, ensure_ascii=False)) # 응답 바디 출력
이 출력 결과를 통해 요청이 성공했는지와 서버에서 반환한 데이터를 확인할 수 있습니다.
이처럼 REST API를 활용하면 프로그램을 통해 주식 매매를 쉽게 요청할 수 있습니다. 처음에는 조금 낯설
수 있지만, 한 번 익숙해지면 매우 편리하게 활용할 수 있습니다.
Web Socket 이해하기
Web Socket이란
웹소켓(WebSocket)은 실시간으로 데이터를 주고받는 기술입니다. 예를 들어, 주식 시세나 채팅을 할 때, 새로고침없이도 계속 업데이트되는 정보를 본 적이 있을겁니다. 바로 이런 기능을 가능하게 하는 것이 웹소켓입니다.
웹소켓과 기존 방식의 차이
우리가 웹에서 정보를 가져올 때 보통은 HTTP를 사용합니다. HTTP는 요청(Request)을 보내고 응답(Response)을 받아야 합니다. 즉, 웹페이지가 데이터를 새로 받아오려면, 계속해서 요청을 보내야 합니다. 하지만 웹소켓은 다릅니다! 한 번 연결하면, 서버와 클라이언트(사용자) 사이에 직접 연결된 통로가 생겨서 실시간으로 데이터를 주고받을 수 있습니다.
쉽게 말해, 아래와 같이 설명할 수 있습니다.
- HTTP: "야 서버야, 새로운 정보 있어?" → 서버가 답함 (필요할 때마다 계속 물어봐야
- WebSocket: "서버야, 나랑 연결 유지해!" → 서버가 알아서 새로운 정보가 생기면 바로 알려줌
그러면 웹소켓을 왜 사용할까요?
- 실시간 데이터 전송: 주식 시세, 채팅, 게임에서 즉시 반응이 필요할 때 사용합니다.
- 양방향 통신: 서버도 먼저 데이터를 보낼 수 있어요! (HTTP는 요청을 보내야만 응답이 옴)
- 연결 유지: 한 번 연결하면 계속 사용할 수 있어서 빠릅니다.
웹소켓 vs. HTTP 비교
| 특징 | HTTP | WebSocket |
|---|---|---|
| 연결방식 | 요청할 때마다 새 연결 | 한 번 연결되면 유지 |
| 데이터 전송 방향 |
클라이언트 → 서버 (단방향) | 클라이언트 ↔ 서버 (양방향) |
| 실시간 처리 |
요청해야만 응답 | 서버가 알아서 데이터 전송 |
| 사용 예시 | 웹사이트(일반적인 브라우징) | 채팅, 주식 시세, 게임 |
실시간 시세 조회 따라 해보기
웹소켓을 활용하는 실제 Python 코드를 하나씩 쉽게 설명하겠습니다.
1. 필요한 라이브러리 가져오기
1-1. 라이브러리 다운로드
Python
pip install asyncio
pip install websockets
1-2. 라이브러리 Import
Python
import asyncio
import websockets
import json
- asyncio: 비동기 작업을 쉽게 처리할 수 있게 해줍니다. (비동기 작업은 요청과 응답이 동시에 일어나지 않는 방식으로, 요청을 보내고 응답을 기다리는 동기 작업과는 달리 그 응답을 기다리지 않고 또 다른 요청을 병렬적으로 보낼 수 있는 방식을 말합니다. 그렇기에 시간이 오래 걸리는 작업을 효율적으로 실행하는 방식이기도 합니다.)
- websockets: 웹소켓을 사용할 수 있도록 도와주는 도구입니다.
- json: 데이터를 JSON 형식(문자열로 변환)으로 다룰 수 있도록 합니다.
2. 웹소켓 서버 정보 설정
Python
SOCKET_URL = 'wss://api.kiwoom.com:10000/api/dostk/websocket' # 접속할 주소
ACCESS_TOKEN = '사용자 AccessToken' # 로그인 후 받은 인증 토큰
- OCKET_URL: 키움증권의 웹소켓 서버 주소
- ACCESS_TOKEN: 사용자의 인증을 확인하는 키
이제 직접 실행해보면서 더 익숙해져 보시길 바라겠습니다.
3. 웹소켓 클라이언트 만들기
Python
class WebSocketClient:
def __init__(self, uri):
self.uri = uri
self.websocket = None
self.connected = False
self.keep_running = True
- self.uri: 연결할 서버의 주소
- self.websocket: 실제 웹소켓 연결을 관리하는 변수
- self.connected: 연결 상태 (True면 연결됨, False면 끊김)
이제 직접 실행해 보면서 더 익숙해져 보시길 바라겠습니다.
4. 서버에 연결하기
Python
async def connect(self):
try:
self.websocket = await websockets.connect(self.uri)
self.connected = True
print("서버와 연결을 시도 중입니다.")
# 로그인 패킷
param = {
'trnm': 'LOGIN',
'token': ACCESS_TOKEN
}
print('실시간 시세 서버로 로그인 패킷을 전송합니다.')
# 웹소켓 연결 시 로그인 정보 전달
await self.send_message(message=param)
except Exception as e:
print(f'Connection error: {e}')
self.connected = False
- websockets.connect(self.uri): 웹소켓 서버에 연결을 시도합니다.
- 연결이 성공하면 self.connected = True로 변경합니다.
5. 메시지 보내기
Python
async def send_message(self, message):
if not self.connected:
await self.connect() # 연결이 끊어졌다면 재연결
if self.connected:
# message가 문자열이 아니면 JSON으로 직렬화
if not isinstance(message, str):
message = json.dumps(message)
await self.websocket.send(message)
print(f'Message sent: {message}')
- 서버에 데이터를 보낼 때 JSON 형식으로 변환하여 전송합니다.
- 만약 연결이 끊어져 있다면, 자동으로 다시 연결합니다.
6. 서버에서 메시지 받기
Python
async def receive_messages(self):
while self.keep_running:
try:
# 서버로부터 수신한 메시지를 JSON 형식으로 파싱
response = json.loads(await self.websocket.recv())
# 메시지 유형이 LOGIN일 경우 로그인 시도 결과 체크
if response.get('trnm') == 'LOGIN':
if response.get('return_code') != 0:
print('로그인 실패하였습니다. : ', response.get('return_msg'))
await self.disconnect()
else:
print('로그인 성공하였습니다.')
# 메시지 유형이 PING일 경우 수신값 그대로 송신
elif response.get('trnm') == 'PING':
await self.send_message(response)
if response.get('trnm') != 'PING':
print(f'실시간 시세 서버 응답 수신: {response}')
except websockets.ConnectionClosed:
print('Connection closed by the server')
self.connected = False
await self.websocket.close()
- 서버에서 새로운 메시지를 받으면 출력합니다.
- 연결이 끊기면 알림을 표시합니다.
7. 웹소켓 실행하기
Python
async def run(self):
await self.connect()
await self.receive_messages()
- 서버에 연결하고, 메시지를 계속 받을 준비를 합니다.
8. 웹소켓 종료하기
Python
async def disconnect(self):
self.keep_running = False
if self.connected and self.websocket:
await self.websocket.close()
self.connected = False
print('Disconnected from WebSocket server')
- 웹소켓 연결을 종료하는 함수입니다.
9. 프로그램 실행하기
Python
async def main():
# WebSocketClient 전역 변수 선언
websocket_client = WebSocketClient(SOCKET_URL)
# WebSocket 클라이언트를 백그라운드에서 실행합니다.
receive_task = asyncio.create_task(websocket_client.run())
# 실시간 항목 등록
await asyncio.sleep(1)
await websocket_client.send_message({
'trnm': 'REG', # 서비스명
'grp_no': '1', # 그룹번호
'refresh': '1', # 기존등록유지여부
'data': [{ # 실시간 등록 리스트
'item': ['039490'], # 실시간 등록 요소
'type': ['0B'], # 실시간 항목
}]
})
# 수신 작업이 종료될 때까지 대기
await receive_task
# asyncio로 프로그램을 실행합니다.
if __name__ == '__main__':
asyncio.run(main())
- WebSocketClient를 만들어 실행합니다.
- send_message를 이용해 특정 주식 코드 (039490)의 실시간 정보를 요청합니다.
- asyncio.run(main())을 사용하여 프로그램을 실행합니다.
이제 직접 실행해보면서 더 익숙해져 보시길 바라겠습니다.