AI 에이전트 시대의 REST API 설계, 문서·오류·속도 제한을 다시 짜야 하는 이유

핵심 메시지

• 웹 브라우저와 모바일 앱에 이어 AI 에이전트가 REST API의 새로운 소비자가 됐고, 기업이 원하든 원하지 않든 공개된 API는 에이전트에게 호출된다.
• 에이전트는 자연어를 파싱해 움직이므로, 메서드 이름을 그대로 되풀이한 형식적 문서로는 부족하고 호출 제약과 예외 상황까지 설명하는 기계가 이해할 수 있는 문서가 필요하다.
• 오류 응답을 구체적으로 돌려주지 않으면 에이전트는 값을 추측하고 재시도를 반복하며, 그 비용은 결국 API 제공자와 이용자 양쪽이 나눠 낸다.
• 에이전트는 개별 엔드포인트가 아니라 하나의 작업 흐름을 끝내고 싶어 하므로, 여러 호출을 안에서 묶어주는 설계가 훨씬 효율적이다.
• 고정 할당량 방식의 속도 제한은 에이전트 트래픽의 불규칙함을 감당하지 못해, 트래픽을 분석해 조정하는 적응형 방식이 논의되고 있다.

쉽게 이해하기

덴마크에서 열린 개발자 콘퍼런스 NDC 코펜하겐 2026에서 보얀 미하일로프가 'AI 에이전트 시대의 REST API 설계'를 주제로 발표했다. 그는 1981년의 원격 프로시저 호출부터 2000년대의 SOAP, 그리고 자바스크립트와 JSON의 확산과 함께 자리 잡은 REST까지 API의 흐름을 짚은 뒤, 지금 새로운 변화가 일어나고 있다고 말했다. 지금까지 API의 소비자는 웹 클라이언트, 모바일 앱, 그리고 다른 서버였는데 여기에 AI 에이전트가 추가됐다는 것이다.

발표자는 에이전트가 사람과 정보를 처리하는 방식이 다르다는 점을 강조했다. 사람은 화면을 보며 이것저것 시도해보지만, 에이전트는 주어진 요청을 만족시킬 확률이 가장 높은 선택을 고른다. 그래서 에이전트가 추측하지 않도록 기계가 읽을 수 있는 명세를 제공하는 일이 중요해진다. 그 출발점이 개발자들이 가장 지루해하는 작업인 API 문서화다.

그는 문서를 자동 생성하는 것만으로는 부족하다고 지적했다. '주문을 생성한다'는 메서드 설명에 '이 메서드는 주문을 생성합니다'라고 쓰는 관행으로는 에이전트에게 아무런 정보도 주지 못한다는 것이다. 몇 번까지 호출할 수 있는지, 오류가 나면 무엇이 잘못된 것인지, 어떤 값이 허용되는지 같은 이름만으로는 알 수 없는 맥락을 적어야 한다. 이런 문서는 결국 그 API를 쓰는 사람 개발자에게도 도움이 된다.

오류 응답과 일관성도 비용 문제로 이어진다. 검증 라이브러리가 '요청에 문제가 있다' 수준의 메시지만 돌려주면 에이전트는 어떤 필드가 왜 틀렸는지 모른 채 다시 시도한다. 또 같은 API 안에서 규칙이 제각각이면 에이전트가 앞선 예시를 보고 나머지를 유추하는 데 실패해 토큰만 낭비된다. 발표자는 '무엇이 옳은가'보다 '일관성을 지키는 것'이 더 중요하다고 정리했다.

응답 크기와 호출 횟수 역시 새롭게 봐야 할 지점이다. 에이전트가 API를 호출하면 그 응답은 다시 언어 모델을 거쳐 해석되기 때문에, 필요 이상으로 큰 응답은 곧바로 비용이 된다. 반대로 엔드포인트를 잘게 쪼개 열 번 호출하게 만드는 것보다, 내부에서 여러 호출을 묶어 하나의 도구로 노출하는 편이 낫다. MCP로 도구를 노출하거나 웹페이지 자체가 도구를 제공하는 방식도 실험되고 있지만, 발표자는 이 영역이 아직 빠르게 바뀌는 중이라고 덧붙였다.

마지막으로 그는 에이전트도 사람처럼 선호를 갖게 된다고 봤다. 사람이 5초 안에 열리지 않는 페이지를 닫아버리듯, 에이전트는 더 명확하고 효율적인 API를 골라 목표를 달성한다는 것이다. 그래서 API 품질을 회사의 지표로 삼고 문서·성능·보안을 점검하라고 권했다. 자연어만으로 사내 AI 상담 창구를 파고드는 시도가 늘고 있다는 보안 경고도 함께 남겼다.

주요 인사이트

• API를 '사람 개발자용 인터페이스'로만 보던 관점이 흔들린다. 발표자의 표현대로 지금의 서비스는 사람용 문과 에이전트용 문을 함께 가진 건물이고, 한쪽이 부실하면 다른 쪽도 영향을 받는다.
• 문서화 부채가 곧바로 운영 비용으로 환산된다. 부실한 설명과 모호한 오류는 에이전트의 추측과 재시도를 부르고, 그 호출이 만드는 토큰과 로그는 실제 청구서로 돌아온다.
• 에이전트의 단위는 엔드포인트가 아니라 작업 흐름이다. 기존 REST 엔드포인트를 1대1로 도구에 대응시키면 얻는 것이 거의 없고, 여러 호출을 묶어 하나의 목표를 끝내주는 설계가 필요하다.
• 멱등성과 속도 제한은 이제 방어 장치가 아니라 필수 전제다. 에이전트는 같은 요청을 반복 호출할 수 있고 트래픽 패턴도 불규칙해, 고정 할당량만으로는 정상 이용까지 막게 된다.
• 경쟁 구도도 바뀐다. 사용자 경험 대신 API 품질에만 집중한 후발 주자가 에이전트에게 먼저 선택받을 수 있다는 것이 발표자의 경고다.

자주 묻는 질문

관련 AI 소식