너무 작은 API 서버는 무엇으로 만들어야 하는가

Scope

핵심 질문

기능이 한두 개뿐인 아주 작은 HTTP API를 만들 때 언어·프레임워크·배포방식을 어떻게 고르는 것이 좋은가?

Research

핵심 근거

작은 API에서는 runtime 성능보다 deployment 단순성, dependency 수, cold start, observability가 더 중요할 수 있다.
이미 사용 중인 언어와 플랫폼을 재사용하면 운영복잡도를 크게 줄일 수 있다.
워크플로 도구의 webhook으로 충분한 경우 별도 서버를 만들 필요가 없지만 호출빈도와 latency가 높으면 전용 서비스가 낫다.

참고 자료

일반적인 분산시스템·데이터 엔지니어링 설계 원칙

Draft

API가 아주 작다면 최고의 언어보다 가장 적은 운영요소를 만드는 선택이 보통 좋다.

먼저 서버가 필요한지 본다

하루 몇 번 호출하고 로직이 외부 API 두세 개를 연결하는 정도라면 n8n이나 Windmill 같은 automation endpoint가 충분할 수 있다. 다만 먼저 접근 가능한 네트워크와 호출자를 정해야 한다. 공개 또는 신뢰할 수 없는 호출을 허용한다면 workflow endpoint에도 요청별 인증·권한 확인이 필요하다.

반대로 초당 여러 번 호출되고 latency가 중요하거나 장기적으로 다른 서비스가 의존한다면 독립 API가 안전하다.

언어 선택

이미 운영 중인 Python, Go, TypeScript 중 하나를 재사용하는 것이 대개 합리적이다.

Python은 개발이 빠르고 library가 많다. Go는 단일 binary와 낮은 메모리 사용량이 장점이다. Bun/Node는 TypeScript ecosystem과 빠른 iteration이 좋다.

과도한 프레임워크를 피한다

endpoint 하나에 대형 framework와 DB, queue를 처음부터 넣을 필요는 없다. HTTP routing, input validation, logging, graceful shutdown에서 시작하되, 외부 접근이 가능하면 TLS, 요청별 인증·권한, 최소권한 실행주체와 입력 크기·rate·부작용 한도를 기본 경계에 포함한다. 필요한 기능은 실제 요구에 따라 확장한다.

핵심

작은 API에서 중요한 것은 최고 benchmark가 아니라 배포와 장애대응 비용이다. 이미 익숙한 runtime으로 가장 단순하게 운영할 수 있는 구조가 보통 정답에 가깝다.