트렌드브리프
REST API 뜻과 설계 원칙, 키움증권 API 사례

REST API 뜻과 설계 원칙, 키움증권 API 사례

게시 · 약 7분 분량

AI 요약

REST API는 로이 필딩이 2000년 논문에서 정의한 웹 설계 방식으로, 자원을 URI로 가리키고 GET·POST·PUT·DELETE로 다룬다. 설계 규칙과 상태 코드, 키움증권·공공데이터 API 사례까지 개발자 눈높이로 짚었다.

목차
  1. REST API의 뜻, 한 줄로 정리하면
  2. REST가 지키기로 한 제약들
  3. REST API는 어떻게 설계하나
  4. 키움증권 REST API는 어떻게 인증하나
  5. 공공데이터·핀테크에서 REST API는 어떻게 쓰나
  6. 처음 설계한다면 이 순서로

REST API는 웹에서 자원을 주고받는 방식을 정한 설계 규칙이다. 주소(URI)로 자원을 가리키고, GET·POST·PUT·DELETE 같은 HTTP 메서드로 그 자원을 조회·생성·수정·삭제한다. 이 개념은 로이 필딩이 2000년 UC 어바인 박사 논문 'Architectural Styles and the Design of Network-based Software Architectures'에서 처음 정의했고, 각 HTTP 메서드의 정확한 의미는 MDN 웹 문서가 정리해 두고 있다.

이 글은 REST의 뜻과 API 설계 기본기를 개발자 눈높이로 짚고, 국내에서 자주 검색되는 키움증권 REST API를 사례로 든다. 2026년 7월 기준 키움증권을 비롯한 증권사들이 REST 방식 오픈 API를 제공한다. GraphQL이나 gRPC 같은 다른 통신 방식은 여기서 다루지 않는다.

REST API의 뜻, 한 줄로 정리하면

REST는 'Representational State Transfer(표현 상태 전이)'의 약자다. 서버에 있는 자원의 상태를 표현(대개 JSON 텍스트)으로 바꿔 주고받는다는 뜻이다.

구성은 세 가지다. 무엇을 다룰지 가리키는 자원(URI), 그 자원을 어떻게 할지 정하는 행위(HTTP 메서드), 오가는 데이터의 형식인 표현(JSON·XML)이다. 예를 들어 GET /users/1024는 '1024번 사용자를 조회한다'는 한 문장이 URI와 메서드로 쪼개진 형태다.

필딩은 HTTP 규격을 만든 사람 중 한 명이다. 그는 이미 잘 설계된 웹(HTTP)을 제대로 활용하자는 취지로 REST를 제안했다. 그래서 REST는 새 기술이라기보다 HTTP를 원래 의도대로 쓰는 방법에 가깝다.

REST가 지키기로 한 제약들

필딩의 논문은 REST를 몇 가지 제약(constraint)의 묶음으로 정의한다. 이 제약을 지켜야 'RESTful하다'고 부른다.

실무에서 가장 자주 걸리는 지점은 무상태다. 서버가 로그인 상태를 들고 있지 않으니, 뒤에서 볼 키움증권 API처럼 요청 헤더에 접근 토큰을 실어 보내는 구조가 여기서 나온다.

REST API는 어떻게 설계하나

설계의 뼈대는 두 문장으로 요약된다. 자원은 명사형 URI로 표현하고, 그 자원에 대한 행위는 HTTP 메서드로 구분한다. URI에 getUser나 deletePost 같은 동사를 넣지 않는 게 핵심이다.

MDN 웹 문서와 널리 쓰이는 관행을 따르면 URI 규칙은 이렇게 정리된다.

행위는 메서드가 맡는다. 여기서 두 성질을 알아 두면 좋다. '안전(safe)'은 서버 데이터를 바꾸지 않는다는 뜻이고, '멱등(idempotent)'은 같은 요청을 여러 번 보내도 결과가 같다는 뜻이다. MDN 웹 문서 기준 각 메서드의 성질은 다음과 같다.

메서드용도안전성멱등성
GET자원 조회안전멱등
POST자원 생성비안전비멱등
PUT자원 전체 교체비안전멱등
PATCH자원 부분 수정비안전보통 비멱등
DELETE자원 삭제비안전멱등

PUT과 PATCH를 헷갈리기 쉽다. PUT은 자원 전체를 통째로 교체하고, PATCH는 일부 필드만 고친다. 그래서 같은 PUT을 두 번 보내면 결과가 같지만(멱등), POST로 생성을 두 번 보내면 자원이 두 개 생긴다(비멱등).

응답에는 상태 코드로 결과를 알린다. 자주 쓰는 코드는 다음과 같다.

실제 요청은 이런 모양이다.

# 사용자 목록 조회 (컬렉션)
GET /v1/users

# 특정 사용자 조회
GET /v1/users/1024

# 새 사용자 생성
POST /v1/users
Content-Type: application/json

{ "name": "김개발", "team": "backend" }

키움증권 REST API는 어떻게 인증하나

앱키(App Key)와 시크릿(Secret Key)으로 접근 토큰을 먼저 발급받고, 이후 모든 요청 헤더에 그 토큰을 실어 보낸다. 키움증권 공식 개발자 포털이 안내하는 방식이다.

키움증권은 공식 REST API 포털에서 오픈 API를 안내한다. 이 포털에 따르면 사용자는 본인 명의 계좌로 신청·동의한 뒤 앱키와 시크릿을 발급받고, 이 둘로 접근 토큰을 얻어 인증한다. 시세처럼 실시간으로 바뀌는 데이터는 WebSocket(연결을 유지한 채 서버가 데이터를 계속 밀어주는 통신 방식)으로 받고, 과도한 호출을 막는 요청 제한(TR limit)이 걸려 있다.

키움증권은 기존 OpenAPI+도 함께 안내한다. 이 방식은 OCX(윈도우 전용 프로그램 부품 기술) 기반이라 32비트 윈도우 환경에서 동작했는데, REST 방식은 이런 운영체제 제약 없이 HTTP만으로 호출한다는 점이 다르다. 그래서 리눅스 서버나 다른 언어에서도 붙이기 수월하다.

토큰 기반 인증은 증권사마다 세부는 달라도 뼈대가 비슷하다. 일반적인 흐름은 이렇다.

# 1. 앱키·시크릿으로 접근 토큰 발급
curl -X POST https://api.example.com/oauth2/token \
 -H "Content-Type: application/json" \
 -d '{ "grant_type": "client_credentials", "appkey": "...", "secretkey": "..." }'

# 2. 발급받은 토큰을 헤더에 실어 호출
curl https://api.example.com/account/balance \
 -H "Authorization: Bearer 발급받은_토큰"

응답은 대개 JSON 구조로 온다. 'Rest API 구조체'를 찾는 사람이 많은데, 이는 JSON 응답을 언어별 타입(예: 자바 클래스, C# struct, 스위프트 Codable)으로 매핑하는 작업을 뜻하는 경우가 많다. 필드 이름과 타입을 문서와 맞춰 두면 파싱 오류를 줄인다.

공공데이터·핀테크에서 REST API는 어떻게 쓰나

공공기관 데이터는 대부분 REST 오픈 API로 열려 있다. 정부가 운영하는 공공데이터포털은 날씨·교통·인구 같은 데이터를 인증키 방식의 REST API로 제공한다. 키움증권 사례처럼, 여기서도 발급받은 인증키를 요청에 실어 보내는 구조가 같다.

핀테크에서는 이 방식이 자동매매나 자산 조회 서비스의 토대가 된다. 증권사 REST API로 시세를 받아 매매 신호를 만들고 주문을 넣는 식이다. 다만 요청 한도와 실계좌 주문이라는 위험이 있으니, 모의투자 환경에서 충분히 검증한 뒤 실전에 붙이는 편이 안전하다.

공식 API가 없는 사이트라면 화면을 자동으로 긁어오는 크롤링을 쓰기도 한다. 이는 웹 검색 엔진이 문서를 수집하는 방식과 뿌리가 같은데, API가 있으면 크롤링보다 형식이 안정적이고 차단될 위험도 적다. 데이터를 다룰 때는 공식 API부터 찾아보는 편이 낫다.

처음 설계한다면 이 순서로

REST API를 처음 만든다면 다음 순서가 실무에서 잘 통한다.

규칙 자체는 단순하지만, 팀 안에서 일관되게 지키는 것이 RESTful한 API의 절반이다.

관련 글

더 많은 글 보기 RSS 구독