2026-11-10 11:58에 작성됨

개발 팁

유지보수할 일을 줄이는 API와 버전 선택 방법

서비스를 운영하면서 유지보수할 일을 줄이기 위해 제가 사용하는 API 선택 기준과 버전 관리 방법을 알려드릴게요. 외부 API가 변경되거나 지원이 종료되는 상황에 대비하는 방법도 함께 소개할게요.

유지보수할 일을 줄이는 API와 버전 선택 방법


저처럼 개발과 운영을 동시에 하는 개발자들은 항상 시간이 부족하고 귀찮죠.
따라서 항상 먼 미래를 바라보며 더 건들지 않아도 매끄럽게 구동되는, 유지보수가 별로 필요 없는 상황을 이상적으로 여기며 그에 따라서 개발합니다. 하지만 뜻대로 되지는 않는 법. 항상 서비스가 제대로 굴러가기 위해서 걸림돌이 하나씩 생기기 마련입니다.


저 역시 항상 유지보수를 하면서 계속 느끼는 점인데 서비스가 제대로 안굴러가거나 문제가 생길 때 대부분의 원인은 api였어요. 지원 중단된 api를 바꾸다보면 거기에 딸려오는 여러 로직도 고쳐야하고 이게 내 서비스를 차지하는 비중이 클수록 거의 모든 코드를 갈아 엎어야하는 불상사가 생깁니다.


이게 생각보다 가벼운 문제는 아닌 게 만들어놓은 서비스가 커지고 많아지다보면 그런 사소한 기능 하나씩 챙기기도 어렵다는 것이죠. 그래서 제가 api를 고를 때 노하우?가 담긴 개발 팁을 작성해볼까 합니다.


이 글에서는 SafePath AI, 상정인사이드, Apice.kr을 만들고 운영하면서 직접 적용했던 방법을 소개해보려고 해요. 각 프로젝트의 구성은 SafePath AI 기술 스택, 상정인사이드 기술 스택, Apice.kr 기술 스택에서도 확인할 수 있어요.




API를 고를 때 기능표만 보지는 마세요.


예전에는 필요한 기능이 있는지, 응답이 잘 오는지만 확인하고 API를 붙이는 경우가 많았어요. 그런데 막상 운영해보면 기능보다 무료 한도나 이용 조건이 더 큰 변수가 되기도 하더라고요. 기능은 직접 보완할 수 있지만, 제공 업체의 요금이나 정책은 제가 정할 수 있는 게 아니니까요.


키 발급 없이 쓸 수 있는 API부터 찾아보세요


가능하면 가입하거나 API 키를 발급받지 않아도 쓸 수 있는 서비스부터 살펴봐요. 기상 데이터를 제공하는 Open-Meteo가 대표적인 예죠. 키 없이 호출할 수 있고, 무료 이용 기준도 공개돼 있어요. 하루 1만 건 미만, 시간당 5,000건, 분당 600건입니다. 오픈소스라 직접 서버를 띄워 사용하는 방법도 있어요.


혼자 쓰는 서비스라면 크게 상관없을 수도 있어요. 하지만 공개 프로젝트를 기준으로 생각하면 이야기가 달라지죠. 가입하거나 API 키를 발급받아야 하는 서비스는 무료 한도가 낮은 경우가 있고, 응답 품질이 좋더라도 비용이 꽤 비쌀 수 있어요. 그래서 처음부터 이런 조건을 잘 살펴보는 편입니다.


다만 이 무료 조건은 비상업적 이용에만 해당해요. 상업 서비스라면 유료 구독이 필요하고, 데이터 라이선스도 CC-BY 4.0이라 출처를 표시해야 하죠. 키가 필요 없다고 해서 별다른 조건까지 없는 건 아니에요. 나중에 서비스 성격이 바뀔 수도 있으니 처음 연결할 때 이용 범위까지 확인해두는 게 좋습니다.


호출 한도는 실제 사용량으로 계산해보세요


공공데이터포털은 API마다 이용 한도가 정해져 있어요. 이용가이드를 보면 개발계정은 하루 평균 1,000건 규모이고, 운영계정은 하루 최대 10만 건까지 제공돼요. 물론 API마다 차이가 있습니다. 개발계정에 1,000건이 주어지는 API도 있고, 100만 건이 주어지는 API도 있거든요. 운영계정은 활용사례를 등록한 뒤 트래픽 증설을 신청할 수도 있어요.


숫자만 보고 한도가 넉넉하다고 판단하기는 어려워요. 하루 방문자가 2,000명이고 한 사람당 API를 세 번 호출한다고 가정해볼게요. 캐시가 없다면 하루 6,000건이 필요하죠. 반대로 캐시 적중률이 90%라면 외부 API로 나가는 요청은 약 600건까지 줄어듭니다.


하루 호출 수 = 하루 방문자 × 방문자당 호출 수 × (1 - 캐시 적중률)


위 방문자 수와 호출 횟수는 계산 방법을 보여주려고 임의로 정한 값이에요. 실제 서비스에서는 화면을 열 때마다 호출하는지, 여러 화면에서 같은 데이터를 공유하는지에 따라 결과가 꽤 달라지거든요. 개발계정으로 시작해도 될지 고민된다면 먼저 예상 트래픽부터 계산해보는 게 좋습니다.


유명한 서비스도 가격이 바뀔 수 있어요


Google Maps Platform처럼 이용자가 많고 잘 알려진 API도 예외는 아니에요. 2025년 3월부터 월 200달러 크레딧이 사라지고 SKU별 무료 사용량으로 바뀌었죠. Essentials는 월 10,000건, Pro는 5,000건, Enterprise는 1,000건이 무료 사용량으로 정해졌어요. 예전 크레딧을 기준으로 비용을 예상해뒀다면 다시 계산해야 할 만큼 큰 변화였습니다.


그래서 저는 제공 업체의 규모만 보지는 않아요. 응답 형식이 얼마나 일반적인지도 함께 확인하죠. WFS나 REST/JSON처럼 익숙한 규격을 사용하면 다른 제공자로 옮길 때 부담이 덜하거든요. 반대로 특정 API의 응답 구조를 서비스 여기저기에서 직접 사용하고 있으면 교체 작업이 커질 수밖에 없습니다.


공개 서버는 여러 사람이 함께 쓰는 자원이에요


SafePath AI에서 주소를 좌표로 바꿀 때는 OpenStreetMap의 Nominatim을 사용해요. 이때 특히 신경 쓴 부분은 공개 서버의 요청 정책이었어요. 서비스 전체를 기준으로 초당 최대 한 번만 요청할 수 있고, 서비스를 식별할 수 있는 User-Agent도 보내야 하죠. 결과를 캐시해야 한다는 조건도 있어요. 정책이 바뀔 수 있고, 과도하게 사용하면 접근이 제한될 수 있다는 안내도 명시돼 있습니다.


공개 서버는 제 서비스만을 위해 운영되는 게 아니죠. 요청을 너무 많이 보내면 다른 이용자에게도 영향을 줄 수 있어요. SafePath AI에서는 한 번 변환한 주소를 파일에 저장해 다시 사용하고, 새 요청 사이에는 1초 간격을 뒀습니다. 한 번에 새로 변환하는 주소 수도 제한했고요. 공개 서버를 이용한다면 이런 제약을 지키면서 사용하는 게 맞다고 생각해요.



API 제공량이 부족할 때는 이렇게 해보세요


필요한 API들의 하루 무료 제공량이 모두 적다면 포기하기보다 여러 API를 함께 활용하는 방법도 있어요.


  1. 제공량이 적더라도 비슷한 기능을 제공하는 API를 최소 5개 이상 찾아둬요.
  2. 백엔드에서 각 API의 요청과 응답 형식에 맞게 데이터를 가공하는 로직을 추가해요.
  3. 사용 중인 API에서 429 응답이 오면 다음 API로 넘어가도록 처리해둬요.


저는 보통 사용량이 많지 않을 때 각 API의 요청과 응답 형식을 모두 같은 형태로 맞춰두고, 제공량을 함께 활용하는 방법을 사용해요. 이렇게 해두면 한 API의 무료 제공량이 부족할 때도 다른 API로 이어갈 수 있거든요.




외부 API가 바뀌어도 손댈 곳을 줄이는 방법


API를 신중하게 골라도 언젠가는 이용 조건이나 응답 형식이 바뀔 수 있어요. 그래서 외부 서비스와 직접 맞닿는 부분은 서비스 내부 로직과 분리해두려고 합니다. 문제가 생겼을 때 프론트엔드부터 데이터 처리 코드까지 전부 손봐야 하는 상황은 피하고 싶거든요.


외부 API 호출은 서버 한곳에 모아두세요


SafePath AI의 보안등 정보는 국가안전지도(safemap.go.kr)의 WFS API에서 가져와요. 프론트엔드에서 이 API를 직접 호출하는 대신, 서버가 중간에서 요청을 전달하도록 만들었습니다. 외부 API의 주소와 요청 형식, 응답을 가공하는 코드까지 서버 한곳에 모아둔 셈이죠.


나중에 제공자가 바뀌더라도 서버의 연동 부분만 수정하면 돼요. 프론트엔드는 기존에 사용하던 내부 API를 그대로 호출하면 되니 외부 서비스의 변경을 화면까지 끌고 올 필요가 없죠.


이미 받은 결과는 다시 활용하세요


SafePath AI에서는 지오코딩 결과와 히트맵 계산 결과, 경로 계산 결과를 각각 파일로 캐시해요. 같은 주소를 매번 다시 좌표로 바꾸거나, 이미 계산한 경로를 반복해서 계산할 필요는 없으니까요.


캐시를 두면 응답 속도뿐 아니라 외부 API 호출량도 줄어들어요. 서버가 반복해서 처리해야 하는 작업도 자연스럽게 줄어들죠. 캐싱을 적용해 서버 부하를 줄이는 방법은 한 달 수만 명이 방문하는 1인 개발 서비스, 서버는 어떻게 버틸까에서 조금 더 자세히 다뤘어요.


주 경로가 막혔을 때도 대비해두세요


SafePath AI는 도로망 그래프를 OSMnx와 NetworkX로 직접 계산해요. 두 라이브러리를 사용할 수 없는 환경에서는 공개 라우팅 서버인 OSRM을 대안으로 사용하도록 해뒀습니다. 주 경로 계산이 실패하더라도 경로 안내 기능 전체가 멈추지는 않도록 마련한 방법이죠.


실시간 정보가 아니라면 파일로 관리해보세요


비상벨이나 안심지킴이집, CCTV 위치처럼 실시간으로 바뀌지 않는 데이터는 공공데이터 CSV를 사용해요. 서버가 시작될 때 파일을 읽어 메모리에 올려두면 매번 API를 호출하지 않아도 되죠. 데이터가 갱신되면 파일만 교체하면 됩니다.


CSV를 읽을 때 한 번 걸렸던 부분은 인코딩이었어요. 공공데이터 파일마다 인코딩이 달라서 cp949, euc-kr, utf-8 순서로 읽기를 시도하도록 처리했습니다.


반복해서 바뀌는 목록은 자동으로 갱신하세요


상정인사이드에서는 Tor 출구 노드 목록을 1시간마다, SoftEther VPN 서버 목록을 10분마다 받아 차단 목록에 반영해요. 이런 목록을 사람이 직접 확인하고 갱신한다고 생각해보세요. 바쁜 날에는 주기를 놓치기 쉽겠죠. 처음 설정할 때는 조금 번거롭더라도 나중을 생각하면 자동 갱신 정도는 마련해두는 게 좋습니다.


캐시와 호출 간격, 실패 처리를 한 함수에 모으면 아래처럼 구성할 수 있어요. 전체 예시 코드를 새로 작성하려고 했는데, 상정인사이드 백엔드 코드를 가져와 조금 바꿔봤어요. 보안 때문에 실제 운영에 사용하는 코드와는 차이가 있습니다.


import json
import time
import requests
from pathlib import Path
CACHE_FILE = Path("geocode_cache.json")
if CACHE_FILE.exists():
    cache = json.loads(CACHE_FILE.read_text(encoding="utf-8"))
else:
    cache = {}
def geocode(address):
    if address in cache:
        return cache[address]
    time.sleep(1)
    try:
        response = requests.get(
            "https://nominatim.openstreetmap.org/search",
            params={"q": address, "format": "json", "limit": 1},
            headers={"User-Agent": "my-service/1.0 ([email protected])"},
            timeout=5,
        )
        response.raise_for_status()
        items = response.json()
    except requests.RequestException:
        return None
    if not items:
        return None
    cache[address] = [float(items[0]["lat"]), float(items[0]["lon"])]
    CACHE_FILE.write_text(
        json.dumps(cache, ensure_ascii=False),
        encoding="utf-8",
    )
    return cache[address]




언어와 프레임워크 버전은 지원 기간까지 보고 고르세요


새 버전이 나오면 한 번 써보고 싶어지죠. 하지만 운영 중인 서비스라면 최신 기능보다 업데이트와 보안 패치를 얼마나 오래 받을 수 있는지가 더 중요할 때가 많아요. 서버 OS를 고를 때 Ubuntu Server LTS를 권했던 이유(웹서버 글)와도 같은 맥락입니다.


2026년 11월 기준으로 주요 런타임과 프레임워크의 지원 일정을 정리해봤어요.


구분 버전 현재 상태 지원 종료
Node.js 22 Maintenance LTS 2027년 4월 30일
Node.js 24 Maintenance LTS 2028년 4월 30일
Node.js 26 Active LTS (2026년 10월 28일 진입) 2029년 4월 30일
Python 3.11 보안 패치만 2027년 10월
Python 3.12 보안 패치만 2028년 10월
Python 3.13 보안 패치만 2029년 10월
Python 3.14 버그 수정 지원 중 2030년 10월
Python 3.15 2026년 10월 9일 출시 약 2031년 10월
Next.js 15 Maintenance LTS 기간 종료 2026년 10월 21일 (정책 기준 계산)
Next.js 16 Active LTS 2027년 10월 (정책 기준 계산)


Node.js 26은 짝수 버전만 LTS가 되던 기존 방식의 마지막 버전이에요. 27부터는 매년 4월 새 메이저 버전이 나오고, 10월에 LTS로 전환됩니다. 즉, 모든 릴리스가 LTS 대상이 되는 방식이죠. Node.js 27은 2027년 4월 출시, 2030년 4월 지원 종료가 예정돼 있지만 공식 안내에도 일정은 바뀔 수 있다고 적혀 있어요.


Python은 매년 10월 새 버전이 나오고, 출시 후 5년간 지원돼요. Java는 6개월마다 새 버전이 나오며 2년마다 LTS가 출시되죠. 현재 LTS는 2025년 9월에 나온 Java 25이고, Oracle 로드맵을 기준으로 다음 LTS는 2027년에 나올 Java 29입니다.


그렇다고 무조건 최신 버전을 선택할 필요는 없어요. 너무 오래된 버전만 아니라면 2~3년 정도 지난 버전도 괜찮습니다. 그사이에 큰 문제가 없었다면, 새 버전보다 이미 많은 사람이 사용하면서 검증된 버전이 더 안정적일 때도 있거든요.


지원 종료일은 미리 기록해두세요


지원이 끝났다고 프로그램이 다음 날 바로 멈추는 건 아니죠. 더 큰 문제는 취약점이 발견돼도 보안 패치를 받을 수 없다는 점이에요. 시간이 지나면 주요 라이브러리도 해당 버전 지원을 중단합니다. 이때 한꺼번에 버전을 올리려면 호환성까지 확인해야 해서 일이 커질 수밖에 없어요.


저는 프로젝트 README에 사용 중인 런타임 버전과 지원 종료일을 함께 적어두는 편이에요.


개발 환경마다 버전이 달라지지 않도록 맞춰두세요


같은 프로젝트인데 제 컴퓨터에서는 잘 실행되고 다른 환경에서는 오류가 난다면 버전 차이부터 의심하게 되죠. Node.js 프로젝트라면 package.json의 engines 필드에 사용할 버전 범위를 적고, 락파일도 저장소에 커밋해두세요. 설치할 때 npm ci를 사용하면 락파일에 기록된 의존성을 기준으로 설치할 수 있어요. Docker 이미지도 latest 대신 node:26처럼 버전을 지정하는 쪽을 선호합니다.


# Node.js 버전 지정
echo 26 > .nvmrc
npm ci
# Python 가상환경과 패키지 목록 기록
python3 -m venv .venv
source .venv/bin/activate
pip freeze > requirements.txt


프레임워크는 런타임보다 자주 확인하세요


Next.js는 새 메이저 버전이 나오면 이전 버전이 Active LTS에서 Maintenance LTS로 넘어가요. Active LTS에서는 새 기능과 보안 패치를 받을 수 있지만, Maintenance LTS에서는 중요한 버그 수정과 보안 업데이트 위주로 지원하죠. 두 기간을 합친 지원 기간은 출시 후 2년입니다.


이 기준으로 보면 2024년 10월 21일 출시된 Next.js 15는 2026년 10월 21일 지원이 끝났고, 2025년 10월 21일 출시된 16은 현재 Active LTS예요. 백엔드 런타임이 3~5년 지원되는 경우와 비교하면 프론트엔드 프레임워크는 업그레이드 시점을 더 자주 확인해야겠죠.


프레임워크를 바꾸더라도 비즈니스 로직까지 전부 다시 작성하지 않도록 구조를 나눠두면 편해요. 계산이나 데이터 처리처럼 프레임워크와 관계없는 코드는 별도 모듈로 분리하고, 프레임워크 전용 기능은 필요한 부분에만 사용하는 식이죠. 라이브러리를 고를 때는 마지막 릴리스 시기와 관리하는 사람 수, 이슈에 대한 응답 속도도 살펴보세요. 관리가 멈춘 패키지가 핵심 기능에 들어가 있으면 나중에 대체하는 데 시간이 꽤 걸리거든요.


라이브러리는 필요한 만큼만 사용하세요


라이브러리를 하나 추가하면 업데이트와 호환성을 확인해야 할 대상도 하나 늘어나요. 간단한 기능이라면 외부 라이브러리 없이 기본 기능만으로 해결할 수 있는지 먼저 살펴보는 편입니다.


Apice.kr에서는 데이터베이스로 SQLite를 선택했어요. 파일 하나로 관리할 수 있어서 별도의 DB 서버를 운영할 필요가 없었거든요. 대신 여러 학생이 동시에 신청할 때 database is locked 오류가 나지 않도록 WAL 모드와 30초 busy_timeout을 설정했습니다. 관리할 구성 요소를 줄이는 것과 실제 사용 상황에 맞게 설정하는 건 별개의 문제라는 걸 보여준 사례였죠.



추가로


npm 모듈을 관리할 때는 ncu를 추천해요.
npm install -g npm-check-updates 명령어로 설치한 다음,
ncu -u만 실행하면 package.json에 적힌 버전을 알아서 올려주거든요.


배포 직전에 한 번씩 확인해보면 좋습니다.




운영하면서 따로 챙겨두면 좋은 것들


의존성 업데이트는 GitHub Dependabot 같은 도구를 켜두면 한결 편해요. 업데이트가 필요하거나 보안 문제가 발견되면 PR로 알려주거든요. 모든 패키지를 매번 직접 확인해야 하는 수고를 줄일 수 있습니다.


차단 점수나 캐시 유효기간, API 호출 간격처럼 운영하면서 바뀔 수 있는 값은 코드에 고정하지 않는 편이에요. 예를 들어 상정인사이드에서 proxycheck.io의 risk score가 80점을 넘으면 차단하는 기준도 환경변수나 설정 파일로 빼둘 수 있죠. 정책을 바꿀 때 코드를 일일이 찾아다니지 않고 값만 수정하면 되니까요.


README에는 실행 방법뿐 아니라 왜 이런 방식을 선택했는지도 짧게 남겨두세요. 몇 달만 지나도 당시 어떤 이유로 그렇게 만들었는지 기억이 흐릿해지거든요. 한두 줄이라도 적혀 있으면 나중에 코드를 다시 들여다볼 때 꽤 도움이 됩니다.


프로세스가 종료됐을 때 자동으로 다시 실행되도록 설정하는 것도 빼놓지 마세요. systemd의 Restart=always나 PM2를 사용할 수 있고, 장애가 생겼을 때 어떤 순서로 확인할지도 문서로 남겨두면 좋습니다. 서버가 내려갔을 때의 대응 방법은 서버 다운 대응 전략에 따로 정리해뒀어요.




마치며


외부 API와 프레임워크의 정책까지 제가 정할 수는 없어요. 정책이 바뀌는 일 자체를 막을 수도 없죠. 대신 바뀐 뒤에 손봐야 할 곳을 줄이는 건 가능합니다. SafePath AI에서 외부 API 호출을 서버에 모으고 결과를 캐시한 것도 그런 이유였어요.


모든 상황을 미리 대비하려고 하면 기능을 만드는 시간보다 대비하는 시간이 더 길어질 수도 있어요. 지금 서비스 규모에서 실제로 문제가 될 만한 부분부터 챙기고, 나중에 바꾸기로 한 내용은 README에 남겨두는 정도면 충분하다고 생각합니다. 현재로서는 그 정도가 가장 현실적인 방법인 것 같아요.




참고 자료


BY-NC-ND 라이선스

이 글에는 BY-NC-ND 라이선스가 적용되어 있습니다.


더 많은 프로젝트와 개발 이야기가 궁금하다면
윤주원 개발자의 포트폴리오에서
진행했던 프로젝트와 작업들을 더 자세히 확인하실 수 있습니다.
포트폴리오 보러가기