API 연동

쉽게 말하면

API(Application Programming Interface, 애플리케이션 프로그래밍 인터페이스) 란 두 시스템 사이에서 '약속된 소통 방식'이에요. 데이터를 원하는 프론트엔드는 백엔드의 주방에 무작정 들이닥칠 수 없어요. API라는 카운터를 거칩니다. 약속된 형식으로 요청을 보내면, 백엔드가 약속된 형식으로 답해 주죠.

좋은 API에는 명확한 계약이 있어요. 요청에 무엇을 담아야 하는지, 응답은 어떤 모양인지, 오류일 때 어떤 코드를 돌려주는지죠. 계약이 명확하면 프론트엔드와 백엔드를 각자 독립적으로 개발할 수 있고, AI에게 올바른 연동 코드를 생성하게 하기도 한결 쉬워져요.

아키텍처

동작 흐름

좋은 계약과 나쁜 계약

어떤 API가 연동하기 즐거운지, 골칫거리인지의 차이는 결국 계약으로 귀결돼요.

• 좋은 계약은 명확하고(요청과 응답의 모양이 분명히 적혀 있음), 안정적이며(당신 모르게 슬그머니 바뀌지 않음), 문서가 있고(각 필드가 무슨 뜻인지 찾아볼 수 있음), 버전이 있어요(새 버전은 /v2/로 내고, 옛 /v1/은 그대로 동작함).
• 나쁜 계약은 아무런 예고 없이 바뀌어 그것에 의존하는 모든 것을 망가뜨리고, 날것의 데이터베이스 컬럼이나 스택 트레이스 같은 내부 세부까지 흘리며, 문서가 없어서 거듭 시행착오로 동작을 더듬어 알아낼 수밖에 없어요.

핵심 정리

• API = 시스템 간 '약속된 소통 창구'.
• 핵심은 계약: 요청 형식, 응답 형식, 오류 코드.
• 계약 변경에는 버전을 붙인다(예: /v1/, /v2/). 한 번의 변경으로 전부 망가지는 걸 막는다.