API와 JSON

사람이 보는 답과 기계가 보는 답

앞 강의에서 서버가 요청을 받아 답장을 보낸다는 것을 봤습니다. 그런데 그 답장 안에 무엇이 들어 있는가는 두 가지로 갈립니다.

같은 "3번 상품 정보"를 요청해도 답이 이렇게 다를 수 있습니다.

사람에게 주는 답 (웹 페이지)

<div class="product">
  <h1 style="color:#222">무선 이어폰</h1>
  <span class="price">89,000원</span>
  <button>장바구니</button>
</div>

기계에게 주는 답 (API 응답)

{
  "id": 3,
  "name": "무선 이어폰",
  "price": 89000,
  "inStock": true
}

두 답에는 같은 사실이 담겨 있습니다. 차이는 꾸밈이 있느냐입니다. 첫 번째에는 글자 색, 버튼 모양처럼 사람 눈을 위한 것들이 잔뜩 섞여 있습니다. 두 번째에는 사실만 있습니다.

왜 사실만 남기는가

프로그램은 버튼 모양에 관심이 없습니다. 가격이 89000원이라는 사실만 필요합니다. 꾸밈이 섞여 있으면 프로그램은 그 안에서 숫자를 골라내느라 고생하고, 디자인이 조금만 바뀌어도 망가집니다.

그래서 데이터만 돌려주는 창구를 따로 만듭니다. 이 창구가 API입니다.

API(Application Programming Interface)는 이름이 무섭지만 뜻은 단순합니다. "프로그램을 위한 창구"입니다. 사람용 창구(웹 화면) 옆에 기계용 창구를 하나 더 낸 것입니다.

식당 비유

식당에는 손님이 앉는 홀이 있고, 배달 대행 기사가 오는 뒷문이 있습니다.

• 홀 — 인테리어, 음악, 접시 담음새가 중요합니다. 사람이 있으니까요.
• 뒷문 — 포장된 음식과 주문 번호만 정확하면 됩니다. 기사는 인테리어를 감상하러 온 게 아닙니다.

같은 주방에서 나온 같은 음식이지만 전달 방식이 다릅니다. API는 뒷문입니다.

JSON — 기계용인데 사람도 읽을 수 있는

기계가 읽을 데이터라면 아무 형식이나 써도 될 것 같습니다. 압축해서 알아볼 수 없게 만드는 게 더 효율적일 텐데, 실제로 가장 많이 쓰이는 형식인 JSON은 사람이 눈으로 읽을 수 있게 생겼습니다. 왜일까요?

디버깅 때문입니다. 무언가 잘못됐을 때 사람이 열어보고 "아, price가 문자열로 들어왔네"라고 5초 만에 알아챌 수 있는 것의 가치가, 몇 바이트 아끼는 것보다 훨씬 큽니다.

JSON의 문법은 세 가지뿐입니다.

이게 전부입니다. 이 단순함이 JSON이 이긴 이유입니다.

API는 기능이 아니라 계약이다

여기가 실무에서 가장 중요한 부분입니다.

화면은 마음대로 바꿔도 됩니다. 버튼 색을 바꿔도 아무도 고장나지 않습니다. 하지만 API에서 `price`라는 이름을 `cost`로 바꾸면, 그 API를 쓰던 모든 프로그램이 그 순간 고장납니다. 우리 회사 앱, 협력사 시스템, 내부 정산 도구까지 전부요.

그래서 API는 약속(계약) 으로 취급합니다. 한번 공개하면 마음대로 못 바꿉니다. 바꿔야 하면 새 버전(/v2/products)을 따로 열고, 옛 버전을 한동안 같이 굴립니다.

화면 변경  → 우리 팀 안에서 끝난다
API 변경   → 우리가 모르는 사람들까지 멈춘다

그래서 무엇이 달라지는가

화면과 데이터를 분리하는 순간, 같은 데이터로 여러 가지를 지을 수 있게 됩니다. 웹사이트, 모바일 앱, 협력사 연동, 사내 대시보드가 전부 같은 API 하나를 씁니다. 주방을 하나만 두고 창구를 여러 개 내는 것입니다.

이것이 API가 단순한 기술 선택이 아니라 조직의 구조를 바꾸는 결정인 이유입니다.