API (Application Programming Interface)

화면의 예시 데이터를 실제 응답으로 바꾸기

AI가 만든 관광 정보 화면에 가상 장소 세 개가 보인다고 가정해 봅니다. 화면 구성이 완성돼도 실제 지역 정보가 조회되는 것은 아닙니다. 검색 조건을 API 요청에 넣고 받은 응답을 화면에 표시하는 연결이 필요합니다.

BOAZ의 Open API 교안도 요청과 응답을 확인한 뒤 화면에 연결하는 흐름을 다룹니다. 먼저 작은 요청으로 데이터 형식을 확인하면 화면 문제와 통신 문제를 나눠 볼 수 있습니다.

MDN의 API 정의는 API를 소프트웨어 기능을 사용하는 인터페이스로 설명합니다. 웹 API는 그중 네트워크 요청·응답을 사용하는 한 형태입니다.

요청과 응답에서 확인할 것

응답을 받았다는 사실과 원하는 작업의 성공은 따로 확인합니다. 성공 상태라도 필요한 항목이 비어 있을 수 있고, 요청 형식은 맞아도 계정에 조회 권한이 없을 수 있습니다.

API와 MCP의 역할

API는 서비스가 제공하는 기능의 호출 방법을 정합니다. MCP는 AI 애플리케이션에 도구와 자료를 연결할 때 쓰는 공통 규약입니다. MCP 서버 내부에서 기존 예약 API나 사내 조회 API를 호출하는 구성이 가능합니다.

도구가 연결됐다고 모든 작업을 허용하는 것은 아닙니다. 조회 도구와 수정 도구의 권한을 나누고, 수정 결과는 실제 저장 상태와 대조해야 합니다. 어떤 호출을 허용할지는 가드레일의 일부입니다.

API 키와 사용자 권한은 구분한다

비밀 키를 화면 코드에 넣으면 방문자가 내려받는 파일에 포함될 수 있습니다. 이런 키는 서버에서 보관하고 필요한 요청에만 사용합니다. 로그나 오류 화면에도 키가 나오지 않도록 합니다.

반대로 브라우저 사용을 전제로 발급된 공개 키도 있습니다. 이 경우 키를 숨기는 것만으로 데이터를 보호할 수 없습니다. 요청한 사용자가 그 기록을 읽거나 바꿀 수 있는지는 서버 또는 데이터베이스의 접근 규칙이 검사해야 합니다.

CORS와 프록시는 어디에서 작동하나

CORS는 브라우저가 다른 출처의 응답을 스크립트에 공개해도 되는지 서버의 허용 정보로 판단하는 체계입니다. 요청 종류에 따라 사전 확인 요청도 사용합니다. 모든 교차 출처 요청이 전송되지 못한다는 뜻은 아니며 사용자 인증을 대신하지도 않습니다. MDN CORS 안내

외부 API가 브라우저 직접 호출을 지원하지 않거나 비밀 키를 요구하면, 화면이 자신의 서버를 호출하고 서버가 외부 API를 호출하는 구조를 사용할 수 있습니다. 이 서버 프록시는 호출 가능한 대상과 입력을 제한하고 사용자 권한을 검사해야 합니다.

연결 완료는 실패 상황까지 확인한 뒤 판단한다

정상 데이터 하나만 띄우는 데서 멈추지 않습니다. 검색 결과 없음, 잘못된 입력, 만료된 인증, 느린 응답을 확인합니다. 저장 요청은 재시도할 때 같은 항목을 중복 생성하지 않는지도 살펴봅니다.

PRD에 ‘검색 결과를 보여준다’와 함께 빈 결과와 오류 때의 동작을 적어두면 바이브 코딩에서도 완료 기준이 분명해집니다.