공공 API는 문서대로 안 돌아간다
공공 API의 기술적 해자는 문서 밖에 숨어 있는 운영 조건에 있습니다. 그러나 그 해자는 오픈클로 같은 AI 에이전트가 점점 흡수할 수 있는 운영 지식이기도 합니다. 인간은 방향과 판단에 더 집중할 수 있습니다.
처음에는 제가 뭘 잘못한 줄 알았습니다.
공공데이터포털에서 API 키를 발급받고, 명세서를 읽고, 예제 URL을 그대로 붙여 넣었습니다. 파라미터도 맞았고, 날짜 형식도 맞았고, 키도 문제없어 보였습니다. 그런데 응답은 돌아오지 않았습니다. Bad Request만 계속 떨어졌습니다. 인코딩을 다시 보고, 파라미터 순서를 바꿔보고, 인증키를 다시 받아볼까 고민했습니다. 그렇게 한참을 헤맨 뒤에야 알게 됐습니다. 어떤 공공 API는 curl 요청에 User-Agent: Mozilla/5.0 헤더를 넣어야 제대로 응답한다는 사실을 말입니다.
문서에는 그런 말이 없었습니다.
그 순간 깨달았습니다. 공공 API를 다루는 일은 문서를 읽는 일에서 끝나지 않는다는 점입니다. 더 정확히 말하면, 공공 API의 기술적 해자는 명세서에 적힌 파라미터보다 문서 밖에 숨어 있는 운영 조건에 있습니다. 그리고 이 장벽은 시간이 갈수록 오픈클로 같은 AI 에이전트가 더 잘 흡수할 수 있는 종류의 지식이기도 합니다. 인간은 점점 세부 우회보다 방향과 판단에 더 집중할 수 있습니다.
문제는 호출 성공이 아니라 안정적 운영입니다
공공데이터포털에서 API 키를 받고, 명세서를 읽고, 예제 호출을 복사해 붙여 넣으면 바로 쓸 수 있을 것처럼 보입니다. 처음에는 저도 그렇게 생각했습니다. 문서가 정리되어 있으니 남은 일은 연결만 성공시키는 것이라고 믿었습니다.
실제는 조금 다릅니다.
한 번 연결되는 것과 안정적으로 돌아가는 것은 전혀 다른 문제입니다. 공공 API를 실제 프로젝트에 붙여본 사람이라면 비슷한 경험을 한 번쯤은 합니다. 문서에 적힌 대로 했는데 안 됩니다. 그리고 그 이유가 문서 어디에도 적혀 있지 않습니다.
이건 특정 API 하나의 문제가 아닙니다.
열린국회정보 API를 붙일 때도 비슷한 경험을 했고, 국토부 API를 다룰 때도 그랬습니다. 행안부 인구통계 API는 호출이 아주 느렸습니다. 처음에는 서비스가 불안정한 줄 알았습니다. 실제로는 timeout을 15초 수준으로 늘리고, 요청 사이에 1초 정도 간격을 둬야 안정적으로 수집할 수 있었습니다. 법제처 API는 더 미묘했습니다. 연혁 법령까지 포함해서 검색하려면 target=eflaw를 써야 했지만, 본문까지 같은 방식으로 읽을 수 있는 것은 아니었습니다. 검색은 eflaw, 본문은 다시 target=law와 MST로 가져와야 했습니다.
이 차이를 모르면 검색 결과를 본 것만으로 법령 본문까지 읽었다고 착각하기 쉽습니다.
공공데이터포털 키 활성화도 비슷했습니다. 화면에는 거의 즉시 쓸 수 있을 것처럼 보이지만, 실제로는 조금 기다려야 하는 경우가 적지 않았습니다. 신청 직후 바로 호출하면 인증 오류가 나고, 그 순간부터 사람은 헷갈리기 시작합니다. 이게 키 문제인지, 파라미터 문제인지, 시스템 반영 지연인지 구분이 안 되기 때문입니다. 실제 작업에서는 이런 구분이 아주 중요합니다. 원인을 잘못 짚으면 같은 곳에서 몇 시간을 허비하게 됩니다.
운영 메모가 쌓이면 같은 함정을 다시 밟지 않습니다
이런 일을 몇 번 겪고 나면 한 가지가 분명해집니다.
공공 API를 프로젝트에 붙였다고 말하는 것은 사실 충분하지 않습니다. 진짜 중요한 것은 호출 성공이 아니라 안정적으로 돌리는 것입니다. 한 번 성공한 요청과, 매일 돌아도 깨지지 않는 파이프라인은 전혀 다른 수준의 일입니다.
데모 화면에서 한 번 조회되는 것만으로는 아무 일도 일어나지 않습니다. 다음 날도 돌아야 하고, 다음 주에도 깨지지 않아야 하고, 데이터 형식이 조금 바뀌어도 어디서 문제가 생겼는지 금방 추적할 수 있어야 합니다. 실패했을 때는 왜 실패했는지, 다음에는 무엇을 먼저 확인해야 하는지 바로 떠올라야 합니다. 결국 운영 가능한 구조가 되어야 비로소 쓸모가 생깁니다.
저는 그 지점에서 태도를 바꾸게 됐습니다.
새 API를 붙일 때마다 실무 메모를 남기기 시작했습니다. 어떤 헤더가 필요한지, 어떤 파라미터 조합이 실제로 먹히는지, 응답이 느릴 때는 timeout을 얼마나 줘야 하는지, 인증 오류가 날 때는 얼마나 기다렸다가 다시 봐야 하는지, 실패하면 다음에 무엇을 먼저 확인해야 하는지를 적어두었습니다.
이 메모들은 처음에는 사소해 보입니다. 하지만 두 번째, 세 번째부터 힘을 발휘합니다. 같은 API를 다시 붙일 때 삽질 시간이 눈에 띄게 줄어듭니다. 무엇보다 “왜 안 되지”라는 막막함이 줄어듭니다. 대신 “아, 이건 그때 그 문제일 수 있겠구나”라는 감각이 생깁니다.
그 감각은 문서에서 오지 않았습니다. 운영 메모에서 왔습니다.
오픈클로는 기술적 해자를 운영 지식으로 바꿉니다
그리고 바로 이 지점에서 오픈클로 같은 AI 에이전트의 의미가 생깁니다.
공공 API를 둘러싼 기술적 해자는 분명히 존재합니다. 문서에 없는 헤더 조건, 활성화 지연, 느린 응답, 미묘한 파라미터 차이, 본문 조회 방식의 예외 같은 것들은 처음 붙이는 사람을 쉽게 지치게 만듭니다. 하지만 이런 장벽은 반복적으로 마주칠수록 에이전트가 더 잘 흡수할 수 있는 종류의 문제이기도 합니다.
예를 들어 예전 실패 메모가 충분히 쌓여 있는 상태라면, 오픈클로는 새 수집 작업을 붙일 때 처음부터 다르게 움직일 수 있습니다. 먼저 User-Agent 헤더가 필요한 계열인지 확인하고, 응답이 느린 API에는 timeout과 요청 간격을 보수적으로 잡고, 법령 검색에서는 eflaw와 law를 분리해 처리하고, 인증 오류가 나면 키 자체보다 활성화 지연 가능성을 먼저 의심하는 식입니다. 사람이 30분 동안 헤매며 하나씩 시험하던 순서를, 에이전트는 몇 초 안에 기본 운영 루틴으로 되감아볼 수 있습니다.
한 번 실패한 조건과 우회 방법이 기록으로 남고, 그 기록이 다시 호출 습관으로 굳어지면, 다음부터는 사람이 매번 처음부터 삽질할 필요가 줄어듭니다. 오픈클로는 이런 운영 메모를 축적하고, 예외 처리 패턴을 기억하고, 다시 호출할 때 더 안정적인 경로를 먼저 시도할 수 있습니다. 시간이 갈수록 기술적 해자는 사람을 지치게 하는 벽이라기보다, 에이전트가 축적해가는 운영 지식으로 바뀝니다.
인간은 방향과 판단에 집중하면 됩니다
그러면 사람의 역할은 자연스럽게 달라집니다.
어떤 데이터를 붙일지, 어떤 문제를 풀지, 어디까지 자동화할지, 그 결과를 어떤 판단으로 연결할지를 정하는 일이 더 중요해집니다. 헤더 하나를 더 붙일지, timeout을 몇 초 줄지, 어떤 우회 파라미터를 먼저 시도할지 같은 세부 해법은 에이전트가 더 많이 떠맡고, 인간은 방향과 질문에 더 집중할 수 있습니다.
사람들은 종종 거대한 비전을 먼저 말합니다. 그러나 실제 자동화는 훨씬 사소한 장면에서 시작됩니다. 어떤 API가 문서대로는 안 돌아가고, 누군가가 한참을 헤매다가 겨우 우회 조건을 찾아내고, 그걸 메모로 남기는 장면입니다. 그 지루한 기록이 쌓일수록, 다음 호출은 더 빨라지고 다음 자동화는 더 쉬워집니다. 그리고 어느 순간부터는 사람보다 에이전트가 그 운영 지식을 더 잘 다루게 됩니다.
공공 API의 난점은 사라지지 않습니다. 다만 그 난점은 반복될수록 운영 지식으로 바뀌고, 그 운영 지식은 오픈클로 같은 에이전트가 축적하기에 아주 좋은 재료가 됩니다. 그래서 인간이 해야 할 일도 더 분명해집니다. 같은 함정을 매번 다시 배우는 것이 아니라, 어떤 방향으로 갈지 결정하고 어떤 문제를 풀지 정하는 일입니다.
인간이 매번 같은 함정에 빠질 필요는 없습니다.
인간은 방향을 잡고, 에이전트는 기술적 해자를 넘도록 만드는 것. 저는 공공 API를 다루는 다음 단계가 바로 거기서 시작된다고 생각합니다.
다음 글에서는 AX의 핵심이 왜 거대한 시스템 도입보다, 지금 하는 일을 잘게 쪼개는 데서 시작되는지 써보겠습니다.