본문바로가기

테크 가이드

좋은 데이터 API의 조건 5가지

김진묵
· 2026.11.17

데이터를 가져올 때 API는 가장 깔끔하고 안정적인 방법입니다. 

그런데 막상 써 보면 API마다 사용감이 크게 다릅니다. 어떤 API는 문서만 보고 손쉽게 데이터를 받아 오지만, 어떤 API는 응답 구조가 들쭉날쭉하고, 오류가 나도 이유를 알려 주지 않고, 어느 날 예고 없이 바뀌어 버립니다.

API를 쓰는 입장에서는 이런 차이가 곧 시간과 비용입니다. 응답이 들쭉날쭉하면 예외 처리 코드가 늘어나고, 오류 이유를 모르면 원인을 찾느라 시간을 허비하게 됩니다.

그렇다면 "쓰기 좋은 API"는 무엇이 다를까요? API를 고를 때도, 직접 만들 때도 확인해야 할 다섯 가지 조건을 정리했습니다.





좋은 데이터 API의 조건 5가지

1. 일관된 응답 구조: 같은 질문엔 같은 구조의 답

API를 쓰는 프로그램은 응답의 '구조'를 믿고 데이터를 꺼냅니다. 예를 들어 "가격은 항상 price라는 이름의 숫자로 온다"는 약속이 있어야 코드가 단순해집니다.

이 약속이 깨지는 모습은 생각보다 흔합니다. 같은 가격이 어떤 날은 숫자 3000으로, 어떤 날은 "3,000원"이라는 글자로 옵니다. 상품명이 어떤 응답에서는 productName, 다른 응답에서는 product_name으로 오기도 합니다. 날짜도 20261019, 2026-10-19처럼 형식이 제각각일 수 있습니다.

초보자가 가장 많이 당황하는 함정은 결과 개수에 따라 구조가 바뀌는 경우입니다. 결과가 여러 개면 목록으로 오다가, 딱 1개일 때는 목록이 아닌 단일 항목으로 오는 식이죠. 테스트할 때는 잘 돌던 코드가 결과가 1개인 날 갑자기 오류를 냅니다.



일관된 응답 구조: 나쁜 예 vs 좋은 예


좋은 API는 결과가 0개든 100개든 항상 같은 구조로 답합니다. 필드 이름은 한 가지 규칙으로 통일하고, 가격은 숫자로, 단위는 따로 알려 줍니다. 날짜도 “2026-10-19” 처럼 국제 표준 형식(ISO 8601) 하나로 맞춥니다. 값이 없을 때의 표현도 하나로 정해 둡니다. 어떤 항목은 비어 있고, 어떤 항목은 '-'이고, 어떤 항목은 아예 빠져 있으면 사용하는 쪽은 경우마다 따로 처리해야 하니까요.

데이터가 많을 때는 결과를 여러 페이지로 나눠 주는데, 이때도 전체 개수와 현재 페이지, 다음 페이지 정보가 항상 같은 이름, 같은 자리에 와야 합니다. 그래야 끝까지 빠짐없이 데이터를 가져올 수 있습니다.


2. 명확한 오류 코드: 실패해도 이유를 알려 준다.

API 요청은 언제든 실패할 수 있습니다. 인증키를 잘못 넣을 수도, 하루 호출 한도를 넘길 수도, 제공 서버가 잠시 멈출 수도 있습니다. 중요한 것은 실패를 어떻게 알려 주느냐입니다. 좋은 오류 응답은 두 가지 질문에 답해 줍니다. 무엇이 잘못됐는지, 그리고 어떻게 고치면 되는지입니다.

좋은 API는 프로그램이 구분할 수 있는 오류 종류와, 사람이 읽고 바로 고칠 수 있는 설명을 함께 줍니다. 이런 오류 응답의 구조를 정해 둔 국제 표준(RFC 9457)도 있습니다. 입력값이 여러 개 틀렸다면 한 번에 모두 알려 주는 것도 좋은 습관입니다. 하나 고치면 다음 오류가 나오는 식이면 몇 번이고 다시 요청해야 하니까요.





오류 종류와 설명을 함께 주는 오류 응답


국내 공공데이터포털도 오류 코드 표를 갖추고 있습니다. 예를 들어 '하루 호출 한도 초과'와 '초당 호출 한도 초과'를 서로 다른 코드로 알려 줍니다. 덕분에 사용하는 쪽은 '내일 다시 시도'와 '잠깐 후 다시 시도'를 구분해 대응할 수 있습니다.

반대로 흔한 나쁜 예는, 실패했는데도 '성공'이라고 답하고 본문에만 error라고 적는 것입니다. 그러면 프로그램이 오류 메시지를 데이터로 착각해 그대로 저장해 버릴 수 있습니다.

3. 친절한 문서화: 문서만 보고 API 호출에 성공한다.

API 문서는 사용 설명서이자 약속을 적어 둔 계약서입니다. 문서가 부실하면 사용자는 직접 요청을 보내 보며 응답 구조를 추측해야 합니다. 좋은 API일수록 문서를 열고 첫 데이터를 받기까지 걸리는 시간이 짧습니다.

좋은 문서에는 다음 내용이 꼭 들어 있습니다.

•    시작 가이드: 가입부터 첫 호출까지 따라 할 수 있는 안내

•    인증 방법: 인증키를 어디에, 어떻게 넣는지

•    요청과 응답 설명: 요청 방법과 응답 항목 하나하나의 뜻

•    바로 써 볼 수 있는 예시: 복사해서 그대로 실행해 볼 수 있는 요청·응답

•    오류 코드별 설명과 하루 호출 한도 같은 제한 사항


그리고 무엇보다 문서와 실제 응답이 일치해야 합니다. 예시가 오래돼 실제 응답과 다르다면, 문서가 오히려 혼란을 만듭니다.

4. 안정적인 버전 관리: 바뀌어도 내 코드는 그대로

API도 계속 발전합니다. 문제는 그 변화가 이미 쓰고 있는 사람들의 코드를 깨뜨릴 때입니다. 응답 항목 이름 하나만 바뀌어도, 그 API를 쓰는 많은 서비스가 한꺼번에 멈출 수 있습니다.

그래서 변경은 두 종류로 나눠 생각합니다. 새 기능이나 새 응답 항목을 추가하는 것은 기존 코드를 깨뜨리지 않는 '안전한 변경'입니다. 반면 항목 이름을 바꾸거나 지우는 것, 숫자였던 값을 글자로 바꾸는 것은 기존 코드를 망가뜨리는 '깨지는 변경'입니다.



안전한 변경과 깨지는 변경


좋은 API는 안전한 변경은 자연스럽게 반영하고, 깨지는 변경은 v1, v2처럼 새 버전으로 분리합니다. 미리 공지하고, 이전 버전을 일정 기간 함께 운영해 사용자가 자기 일정에 맞춰 옮겨 갈 수 있게 해 줍니다.

사용하는 쪽에도 좋은 습관이 있습니다. 응답에 모르는 새 항목이 와도 무시하도록 코드를 짜 두고, 사용할 버전을 코드에 분명히 적어 두는 것입니다. 그리고 제공자의 변경 공지를 꼭 챙겨 보세요.

5. 믿을 수 있는 데이터 품질: 언제, 어디서 온 데이터인지 분명하다.

앞의 네 가지가 데이터를 받는 과정에 대한 조건이라면, 마지막은 받은 데이터 자체에 대한 조건입니다. 구조가 완벽해도 값이 오래됐거나 의미가 애매하면, 그 데이터로 내린 결론은 모두 틀리게 됩니다.

홈택스의 사업자 상태 조회를 예로 들어 보겠습니다. 국세청은 같은 정보를 공공데이터포털의 '사업자등록정보 진위확인 및 상태조회' API로도 제공합니다. 거래처의 사업자등록번호를 넣으면 계속 사업 중인지, 휴업·폐업했는지, 과세유형이 무엇인지 알려 주는 서비스입니다. 이 API에는 믿을 수 있는 데이터의 조건이 잘 드러나 있습니다.

먼저 언제 기준의 데이터인지 알 수 있습니다. 응답이 '폐업'이라고만 오면, 지난달 세금계산서를 주고받을 때 이미 폐업 상태였는지 판단할 수 없습니다. 그래서 이 API는 폐업일자를 함께 알려 줍니다. 또 국세청 자료와 30분 주기로 맞춰지고, 새로 등록한 사업자는 반영까지 1~2일 걸릴 수 있다고 미리 안내합니다. 덕분에 방금 등록한 거래처가 조회되지 않아도 오류가 아니라는 것을 알 수 있습니다.

다음으로 무엇을 가리키는 데이터인지 분명합니다. 상호명은 같은 이름이 여럿일 수 있지만, 사업자등록번호는 사업자마다 하나뿐이라 헷갈릴 일이 없습니다. 사업자 상태와 과세유형도 '계속사업자', '간이과세자'처럼 정해진 값으로만 옵니다. 등록되지 않은 번호를 넣으면 빈 값이나 '폐업'이 아니라 등록되지 않은 번호라고 따로 알려 줘서, '없는 사업자'와 '문을 닫은 사업자'를 혼동하지 않게 해 줍니다.

마지막으로 출처가 분명합니다. 국세청이 직접 제공하는 데이터라서, 세금계산서 발행 전 거래처 확인처럼 정확성이 중요한 업무에도 믿고 쓸 수 있습니다.

스크래핑 API에도 같은 기준을

공식 API가 없거나, 있어도 필요한 데이터를 다 주지 않는다면 스크래핑 API라는 선택지도 있습니다. 대행 서비스가 웹페이지를 대신 스크래핑해서, 결과를 API처럼 정리된 데이터로 돌려주는 방식입니다.

홈택스가 좋은 예입니다. 사업자 상태조회는 공식 API가 있지만, 세금계산서 내역이나 신고 내역 같은 본인 자료는 일반 사용자가 바로 쓸 수 있는 공개 API가 없습니다. 스크래핑 API는 사용자가 본인 인증을 하면 이런 자료를 대신 가져오고, 필요한 항목만 골라 내 시스템에 맞는 구조로 받을 수 있게 해 줍니다. 공식 API가 닿지 않는 데이터까지 원하는 구조로 받을 수 있다는 것이 가장 큰 장점입니다.



공식 API와 스크래핑 API의 차이


다만 겉모습은 API여도 데이터가 오는 길이 다릅니다. 공식 API는 제공자의 데이터베이스에서 바로 꺼내 주지만, 스크래핑 API는 대상 웹사이트의 보이는 화면에서 데이터를 뽑아 옵니다. 그래서 다섯 가지 조건을 더 꼼꼼히 봐야 합니다.

특히 중요한 것은 첫 번째 조건입니다. 대상 사이트가 화면을 바꿔도 응답 구조를 그대로 유지해 주는지 확인하세요. 오류도 "사이트 접속 실패", "페이지 없음", "데이터 추출 실패"처럼 나눠서 알려 주는지 봐야 합니다. 데이터를 언제 수집했는지 함께 알려 주는지, 페이지를 실제로 열어 가져오는 만큼 응답 속도는 괜찮은지도 체크 포인트입니다. 추출 성공률과 실패 시 과금 여부도 확인해 두세요.

마무리: 좋은 API는 '예측할 수 있는' API

다섯 가지 조건을 한 문장으로 줄이면, 좋은 데이터 API는 사용하는 사람이 예측할 수 있는 API입니다. 응답 구조를 예측할 수 있고, 실패 이유를 알 수 있고, 사용법이 분명하고, 앞으로의 변화에 대비할 수 있고, 데이터의 의미를 믿을 수 있는 API입니다.

다섯 가지를 모두 갖춘 API는 드물지만, 이 기준을 알고 있으면 무엇을 먼저 확인하고 어떤 부분을 조심해야 할지 판단하기가 훨씬 쉬워집니다. API를 직접 만든다면, 이 다섯 가지가 그대로 설계 체크리스트가 됩니다.

다음에 API를 고를 일이 생기면 아래 점검표로 한번 확인해 보세요.



좋은 데이터 API 점검표

 

출처

•    IETF, RFC 9457: Problem Details for HTTP APIs (2023) — https://datatracker.ietf.org/doc/html/rfc9457

•    공공데이터포털, 오픈 API 공통 오류 코드 (API 명세 예시) — https://www.data.go.kr/data/15001043/openapi.do

•    공공데이터포털, 국세청_사업자등록정보 진위확인 및 상태조회 서비스 — https://www.data.go.kr/data/15081808/openapi.do

•    Fern, API design best practices guide (2026) — https://www.buildwithfern.com/post/api-design-best-practices-guide

•    cloro, Web Scraping vs API — https://cloro.dev/blog/web-scraping-vs-api/

•    PromptCloud, Website Crawler vs Scraper vs API — https://www.promptcloud.com/blog/crawler-vs-scraper-vs-api/


  • #API
  • #조건
  • #오류
  • #스크래핑

우리 회사에 맞는 데이터 인프라가 궁금하신가요?

1,000+ 기업이 선택한 인포텍코퍼레이션의 기술력을 직접 경험해보세요.

무료 상담 신청하기