"근데 API가 뭐예요?"
회의실에서 의외로 자주 나오는 첫 질문입니다. 외부 업체가 "API로 연동하면 됩니다"라고 말하고 나간 자리, 사내 회의에서 누군가 슬쩍 손을 들고 묻습니다. 다들 안다고 가정하고 넘어간 그 단어를, 사실은 아무도 같은 그림으로 그리고 있지 않습니다.
이 글은 그 첫 질문에서 시작합니다. API가 정확히 무엇이고(그리고 무엇이 아닌지), 회사 안의 데이터를 외부와 연결할 때 어떤 역할이 필요한지, 그리고 시온랩 API Market이 그 안에서 어떤 역할을 하는지 차례로 정리합니다.
먼저 한 줄로 정리해 두면, API는 데이터 그 자체가 아닙니다. API는 이미 있는 데이터를 외부에서 같은 모양으로 부를 수 있게 만드는 약속입니다. "API를 사다 붙인다"는 표현이 자주 쓰이지만, 실제로 만들어지는 건 데이터 위에 정의되는 호출 규약입니다.
API를 검색하면 이런 그림이 나옵니다
포털에 "API"를 검색하면 대체로 이런 도식이 가장 먼저 보입니다.
보안 정책으로 확대가 제한됩니다
그림이 전달하는 메시지는 단순합니다. 두 시스템 사이에 정해진 모양으로 요청과 응답이 오가도록 만들어 둔 통로, 그게 API입니다. 클라이언트(부르는 쪽)가 정해진 규칙으로 요청을 던지고, 서버(받는 쪽)가 정해진 모양으로 응답을 돌려줍니다.
회사에서 "데이터를 API로 열자"고 할 때 머릿속에 그려지는 게 보통 이 그림입니다. 다만 실제 회사 안에서는 서버 자리에 한 가지 시스템만 놓이지 않습니다. ERP, 사내 DB, 영업 시트, 제조 라인 로그 같은 여러 시스템이 함께 들어 있습니다. 이 글에서는 그 차이를 어떻게 메우는지, 그리고 시온랩이 어떤 역할을 맡는지 단계별로 풀어보겠습니다.
API가 정확히 무엇인가
API는 Application Programming Interface의 줄임말입니다. 풀어서 말하면 "어떤 시스템이 다른 시스템에게 자신의 기능 일부를 정해진 규칙으로 호출할 수 있게 열어둔 창구" 입니다.
식당으로 비유하면 메뉴판에 가깝습니다. 손님은 주방에 들어가지 않습니다. 메뉴판에 적힌 이름을 부르면 정해진 모양의 음식이 나옵니다. 메뉴판이 곧 약속이고, 그 약속이 API입니다. 음식 자체(데이터)는 주방 안에 이미 있고요.
기술적으로는 보통 이렇게 동작합니다.
- 호출하는 쪽(클라이언트)이 정해진 주소로 요청을 보냅니다. 예:
GET https://api.example.com/products/42. - 받는 쪽(서버)이 그 요청을 해석하고, 정해진 모양의 응답을 돌려줍니다. 예:
{ "id": 42, "name": "...", "price": 1000 }. - 호출하는 쪽 코드는 그 응답을 받아 자기 화면이나 후속 작업에 사용합니다.
여기서 핵심은 모양입니다. 응답의 키 이름, 자료형, 인증 방식, 오류 처리 규약. 이 약속이 흔들리면 API는 의미가 없습니다. 반대로 말하면, 데이터가 아무리 많아도 약속이 없으면 그건 아직 API가 아닙니다.
그런데 왜 회사마다 API 도입이 어려운가
데이터는 이미 회사 안 어딘가에 있습니다. 영업이 쓰는 시트, 개발팀의 사내 DB, 회계가 누르는 ERP, 제조 라인의 PLC 로그. 흩어져 있을 뿐 사라진 건 아닙니다. 그래서 "API를 새로 만든다" 는 표현보다 "이미 있는 데이터에 약속을 씌운다" 가 실제 작업에 더 가깝습니다.
문제는 그 데이터를 누군가 밖에서 부르려 할 때 시작됩니다.
- 부서마다 데이터 모양이 다릅니다. 영업팀의 "고객 ID"와 회계팀의 "거래처 코드"가 같은 사람을 가리키지만 컬럼 이름이 다릅니다.
- 인증 방식이 시스템마다 제각각입니다. 어떤 건 사번 로그인, 어떤 건 IP 제한, 어떤 건 그냥 사내망 안에서만 열립니다.
- 같은 회사 안에서도 어떤 데이터는 사람이 매번 손으로 복사해 옮깁니다.
다시 말해 도식의 서버 자리는 한 덩어리가 아니라 여러 시스템의 묶음이고, 그 묶음 앞에 공통 약속이 깔려 있지 않습니다. "API로 열자"는 결정이 곧장 "그러려면 우리부터 정리해야 한다"는 숙제로 돌아오는 이유입니다. 그리고 그 정리 작업의 분량은 보통, 호출 규약을 정의하는 일보다 더 큽니다.
시온랩 API Market이 하는 역할
시온랩 API Market은 그 정리 작업까지 포함해 설계·구축·운영하기 위해 만들어졌습니다. 데이터를 새로 만들지 않습니다. 이미 있는 데이터에 일관된 응답 규약을 정의하여, 외부에서 한 가지 형식으로 호출할 수 있도록 합니다. 다시 말해 시온랩은 데이터를 파는 게 아니라, 데이터를 부를 수 있는 약속을 설계·운영합니다.
앞서 본 검색 결과 도식과 매핑해 보면 이렇습니다.
- 도식의 클라이언트는 그대로입니다. 외부 앱·파트너 시스템·자체 서비스 등 호출하는 쪽.
- 도식의 서버 자리에는 회사의 여러 사내 시스템(ERP, DB, 시트 등)이 들어옵니다. 데이터의 원천이 여기입니다.
- 그리고 그 사내 시스템 앞에 시온랩 API Market이 표준화 계층으로 위치합니다. 외부에서 보면 여전히 하나의 API로 통일됩니다.
그림으로 옮기면 이렇습니다.
가운데 파란 박스가 시온랩 API Market의 자리입니다. 외부에서 보는 형식은 한 가지로 통일하고, 안쪽에서는 회사마다 다른 시스템에 맞는 어댑터를 시온랩이 구현합니다.
요청·응답 한 번이 어떻게 흘러가는지 더 들여다보면 이렇습니다.
핵심은 두 가지입니다.
- 클라이언트는 항상 같은 모양으로 호출합니다. 상품(
seq-12)이 무엇이든 인증 키와 응답 구조가 동일합니다. - 원천 시스템과의 차이는 시온랩 쪽 어댑터에서 흡수합니다. 회사 내부에서 ERP가 바뀌거나 시트가 DB로 옮겨가도 외부 호출 코드는 영향받지 않습니다.
API Market의 설계 원칙 세 가지
원칙 1. API는 데이터를 만들지 않는다
API Market의 어떤 상품도 새로운 데이터를 만들어내지 않습니다. 모든 응답은 조직의 기존 시스템에서 출발합니다. 시온랩은 그 사이에서 번역 계층을 담당합니다. 원천이 CSV든, 사내 SOAP든, 종이 문서를 OCR한 결과든 외부에 노출되는 형식은 동일합니다.
원칙 2. 인증과 과금은 상품에 종속되지 않는다
상품마다 인증 방식을 새로 익혀야 한다면 카탈로그의 의미가 없습니다. API Market은 한 번의 키 발급으로 모든 상품을 호출하고, 호출량은 상품별로 분리해서 집계합니다. 회계 정산을 호출량 단위로 자동화할 수 있습니다.
원칙 3. 변경은 상품 파일 한 개로 끝난다
/api/[seq] 상품 상세는 src/lib/api-market/products/seq-*.ts 파일 한 개가 곧 한 상품입니다. 가격, 응답 샘플, 다이어그램이 그 파일 안에 모입니다. 비개발자 편집 흐름을 만들기 전까지는 코드가 곧 단일 진실 원천입니다.
어떤 회사가 쓰면 좋은가
- 사내 시스템에 데이터는 있지만, 외부 파트너·자회사·자체 앱에서 동일한 규약으로 부르고 싶은 회사
- 부서별로 산재한 데이터를 상품 카탈로그 형태로 정리하고 싶은 회사
- 데이터 팀이 별도로 없거나, 있어도 API 운영까지 떠안기엔 손이 모자란 회사
회의실에서 "우리 손으로 못 한다"는 말이 나오는 지점이 있다면, 그 말 자체가 기준선입니다. 시온랩은 그 지점부터 작업을 시작합니다.
도입 절차
각 단계는 보통 1~2주 단위로 끊어 진행합니다. 첫 단계에서 데이터의 주인이 분명해지지 않으면 이후가 흔들리기 때문에, 인터뷰 단계에 가장 많은 시간을 둡니다.
더 보기
- API Market 개요: /api
- 상품 카탈로그: /api/market
- 상품 상세 페이지(
/api/[seq])에서 응답 샘플과 런타임 다이어그램을 확인할 수 있습니다.
데이터를 새로 만드는 일이 아니라, 이미 있는 데이터를 외부에서 동일한 형식으로 호출할 수 있도록 하는 일. 시온랩 API Market은 이 한 가지 역할에 집중합니다.
