#02. API란

꾸꾸·2022년 8월 25일

API(Application Programming Interface) 서로 다른 소프트웨어 시스템과 통신하기 위해서 따라야 할 규칙들을 정의한 것을 말한다.

놀랍게도 모든 웹서비스는 사실 API의 일종이라고 볼 수 있다. 하지만 API가 모두 웹서비스인 것은 아니다. API에 대한 직관적인 이해를 위해 아래 그림을 보자.

그림1: 웹페이지의 API 사용 방법

클라이언트인 크롬 브라우저는 서버에 있는 HTML이나 Data를 화면에 그려주는 역할을 한다. 클라이언트는 서버에 요청(Request)하고 응답(Response)받는 과정을 통해 화면에 그릴 내용을 받아오는데, 이 때 클라이언트는 서버의 API를 사용하여 요청을 하게 된다.

첫번째로, HTML을 받는 예시를 살펴보겠다. 만약 내가 네이버 검색에 '뉴진스'를 검색해 'https://search.naver.com/search.naver?query=뉴진스' 에 해당하는 화면을 내가 보고 있다면, 그것은 search.naver.com이라는 도메인 서버에 /search.naver라는 API로 요청을 보냈고, 이 때 파라미터 값으로 query=뉴진스를 주었고, 그 결과값이 화면에 뜨게 된 것이다. 참고로 해당 url은 이 뒤에 살펴볼 REST API를 사용한 것이다.

그림2: 클라이언트가 서버로부터 HTML을 받은 결과

데이터만 받는 경우에는 API를 통해 요청값을 보내 서버의 DataBase에서 데이터 값을 받아와 응답값이 화면에 출력된다. 아래는 주식시세 API를 사용하여 삼성전자의 현재가를 조회했을 때 받을 수 있는 응답값으로, JSON 형식으로 출력되었다.

{
    "output": {
        "iscd_stat_cls_code": "55",
        "marg_rate": "20.00",
        "rprs_mrkt_kor_name": "KOSPI200",
        "bstp_kor_isnm": "전기.전자",
        "temp_stop_yn": "N",
        "oprc_rang_cont_yn": "N",
        "clpr_rang_cont_yn": "N",
        "crdt_able_yn": "Y",
        ...
        "last_ssts_cntg_qty": "575821",
        "invt_caful_yn": "N",
        "mrkt_warn_cls_code": "00",
        "short_over_yn": "N",
        "sltr_yn": "N"
    },
    "rt_cd": "0",
    "msg_cd": "MCA00000",
    "msg1": "정상처리 되었습니다."
}

그림3: 클라이언트가 서버로부터 Data를 받은 결과

꼭 알아두어야 할 API 종류

그렇다면 꼭 알아두어야 할 API의 종류에는 무엇이 있을까.

SOAP API는 과거에 많이 사용되었던 API이다. 클라이언트와 서버는 XML을 사용하여 메시지를 교환한다.

그림4: SOAP API 호출 예시 그림

Websocket API는 클라이언트와 서버 간의 양방향 통신을 지원하는 최신 API이다. JSON 객체를 사용하여 데이터를 전달한다. 세션 연결이 필요하며, 실시간 통신이 가능하다. 아래의 웹소켓 API 결과값을 보면, 해당 API는 세션 연결 확인을 위해 클라이언트와 서버 간 핑퐁메시지를 계속해서 주고받고 있다.

{"header":{"tr_id":"H0STCNI9","tr_key":"abc123","encrypt":"N"},"body":{"rt_cd":"0","msg_cd":"OPSP0000","msg1":"SUBSCRIBE SUCCESS","output":{"iv":"123456789abcdefcg","key":"123456789abcdefcg123456789abcdefcg"}}}
### RETURN CODE [ 0 ] MSG [ SUBSCRIBE SUCCESS ]
...
### ERROR RETURN CODE [ 1 ] MSG [ ALREADY IN SUBSCRIBE ]
{"header":{"tr_id":"PINGPONG","datetime":"20220727132058"}}
### RECV [PINGPONG] [{"header":{"tr_id":"PINGPONG","datetime":"20220727132058"}}]
### SEND [PINGPONG] [{"header":{"tr_id":"PINGPONG","datetime":"20220727132058"}}]
{"header":{"tr_id":"PINGPONG","datetime":"20220727132108"}}
### RECV [PINGPONG] [{"header":{"tr_id":"PINGPONG","datetime":"20220727132108"}}]
### SEND [PINGPONG] [{"header":

그림5: Websocket API 출력 예시 Python Code

REST API는 오늘날 가장 많이 사용되는 API이다. REST API를 알기 위해서는 REST가 무엇인지부터 알아야 한다. REST는 Representational State Transfer의 준말로, 네트워크 아키텍처 원리의 모음으로, 웹 상의 자료를 HTTP 위에서 별도의 전송 계층 없이 전송하기 위한 간단한 인터페이스를 의미한다. 간단히 말하자면, REST API 하에서 클라이언트와 HTTP 방식으로 데이터를 교환한다. HTTP 방식은 크게 5가지로, GET, POST, PUT, PATCH, DELETE 등이 있다.

import requests
import json

url = "https://openapivts.koreainvestment.com:29443/uapi/domestic-stock/v1/trading/order-cash"

payload = json.dumps({
  "CANO": "12345678",
  "ACNT_PRDT_CD": "01",
  "PDNO": "005930",
  "ORD_DVSN": "00",
  "ORD_QTY": "1",
  "ORD_UNPR": "65000"
})
headers = {
  'content-type': 'application/json',
  'authorization': 'Bearer '
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

그림5: REST API 호출 예시 Python Code

REST API는 Restful API라고도 불리우는데, REST 아키텍처 형식을 지켜서 구현한 다는 점을 생각했을 때 왜 형용사로 쓰이는지 짐작할 수 있다.

REST API가 되기 위한 6가지 아키텍처 조건

가장 많이 논의되는 REST API는 중요한 아키텍처적인 조건이 있다.

1) Uniform Interface
2) Stateless
3) Cacheable
4) Layered System
5) Code on demand
6) Client/Server Architecture

REST API에 관심이 있는 사람이라면 알만한 영상이 있다. "그런 REST API로 괜찮은가" 토스의 개발자 이응준님의 2017년도 강의는 2022년인 지금도 회자될만큼 센세이션했다.

강의의 목차는 아래와 같다.

1) REST란 무엇인가
2) 오늘날의 REST API가 사실은 REST API가 아닌 이유
3) 온전히 REST API를 구현하려면 어떻게 해야 할까
4) 우리는 이제 어떻게 해야 할까

영상에서 가장 핵심적인 부분은 다음과 같다.

꼭 지켜져야 하는 REST 조건에는 2가지가 있다.
첫번째는, self-descriptive message이어야 한다는 것이다. 서버와 클라이언트 간 주고 받는 메시지는 그 자체로 스스로를 설명해야 한다는 것이다.
두번째는, HATEOAS해야 한다는 것이다. 이 조건은 HTTP 헤더나 본문에 링크를 담아 만족시킬 수 있다.