코드 한 줄 쓰기 전, 시니어 엔지니어처럼 API를 설계하는 법
Source: Dev.to
내가 입사한 지 두 번째 주에, 나는 시니어 엔지니어가 하루면 만들 수 있던 API를 3일 동안 리팩토링하는 모습을 지켜봤다.
엔드포인트는 동작했고, 로직도 정확했으며, 코드는 깔끔했다.
하지만 통합 작업이 중간에 이르렀을 때, 프론트엔드 팀이 질문 리스트를 들고 돌아왔다.
- “왜 여기서는 중첩 객체를 반환하고, 저기서는 평탄한 배열을 반환하나요?”
- “페이징은 어디에요? 우리는 페이징이 있을 거라 생각했어요.”
- “에러 코드 14는 무슨 의미인가요?”
아무도 사전에 계획하지 않았다. 모두가 추측했을 뿐이었다. 그리고 3일간의 리팩터링이 이어졌다.
그 주에 나는 어떤 문법이나 프레임워크보다 더 가치 있는 교훈을 얻었다.
가장 비싼 코드는 다시 써야 하는 코드다.
이것은 게으름이 아니다. 우리에게 이 부분을 가르쳐 준 사람은 없었다.
튜토리얼은 API를 어떻게 만드는지 알려준다. 프레임워크, 인증 패턴, 데이터베이스 쿼리를 보여준다. 하지만 코드 첫 줄을 쓰기 전 30분 동안 일어나는 생각, 질문, 범위 정의는 거의 다루지 않는다.
그래서 우리는 자연스럽게 VS Code를 열고 바로 시작한다.
그 결과는 대개 같다. 빠르게 만들고, 예상치 못한 문제에 부딪히고, 급하게 패치를 붙이고, 기술적으로는 동작하지만 유지·확장·설명이 어려운 산출물을 내놓는다.
아래는 내가 배우고 있는 ‘엔드포인트 한 줄도 쓰기 전에’ 진행하는 5단계다.
1️⃣ 먼저 답해야 할 세 가지 질문
세 가지 질문에 명확히 답할 수 없다면, 아직 시작할 준비가 되지 않은 것이다.
-
누가 이 API를 호출할까?
- 프론트엔드 웹 앱?
- 모바일 클라이언트?
- 다른 백엔드 서비스?
- 제3자 개발자?
답에 따라 응답 구조, 인증 방식, 에러 상세 수준이 모두 달라진다.
-
이 API는 무엇을 할까?
- 개발자가 아닌 사람에게 한 문장으로 설명할 수 있는가?
- 두 문장을 넘는다면 범위가 너무 넓을 가능성이 크다.
-
왜 이 API가 필요할까?
- 코드베이스에 비슷한 것이 이미 있나?
- 실제로 확인된 필요인가, 아니면 “언젠가 쓸지도 모른다”는 추측인가?
💡 내 규칙: “30초 안에 엄마에게 이 API를 설명할 수 없으면, 아직 충분히 이해하지 못한 것이다.”
2️⃣ 리소스와 관계 정의하기
종이 한 장을 꺼내거나, 빈 Markdown 파일을 열거나, Miro 보드를 사용한다. 도구는 상관없다.
API가 관리할 리소스와 그 관계를 그린다.
예시 – 간단한 작업 관리 API
리소스
- User
- Project
- Task
- Comment
관계
- User는 여러 Project를 가진다.
- Project는 여러 Task를 가진다.
- Task는 여러 Comment를 가진다.
- Task는 하나의 User(담당자)에게 속한다.
각 리소스마다 현재 필요한 작업을 정의한다.
Task:
✅ GET /tasks → 필터와 함께 작업 리스트
✅ POST /tasks → 작업 생성
✅ GET /tasks/:id → 단일 작업 조회
✅ PATCH /tasks/:id → 작업 업데이트
✅ DELETE /tasks/:id → 작업 삭제
❌ GET /tasks/archive → 아직 필요 없음, 제외
❌ POST /tasks/bulk → 아직 필요 없음, 제외가장 중요한 원칙은 범위를 무자비하게 축소하는 것이다.
지금 추가하는 모든 “있으면 좋은” 엔드포인트는 영원히 관리해야 할 기술 부채가 된다. 실제로 필요하다고 확인된 것만 구축하고, 나머지는 실제 수요가 생겼을 때 추가한다.
💡 시간을 절약하는 질문: “첫 릴리즈에 꼭 필요한가, 아니면 언젠가 쓸지도 모르는가?”
많은 주니어 개발자가 이 단계를 건너뛰고, 그래서 추정치가 항상 빗나간다.
3️⃣ “아직 모르는 것” 찾기 (15분)
코드 한 줄을 쓰기 전, **‘아직 모르는 것’**을 15분 동안 찾아본다. 체크리스트:
인증 & 권한
- 이 API에 인증이 필요한가? 어떤 종류인가? (JWT, API Key, OAuth 등)
- 사용자 역할별 권한 차이가 있는가?
- 어떤 엔드포인트가 공개되고, 어떤 것이 보호되는가?
데이터
- 데이터 출처는? 기존 DB? 새 DB?
- 현재 스키마는 어떻게 생겼는가? 제약 조건은?
- 같은 데이터를 다루는 기존 API가 있는가?
규모
- 하루에 몇 건의 요청이 현실적인가?
- 페이지네이션이 필요한 엔드포인트가 있는가?
- 느릴 수 있는 작업은? (파일 업로드, 외부 API 호출, 무거운 쿼리)
의존성
- 외부 서비스와 연동되는가? (결제 게이트웨이, 이메일, SMS 등)
- 해당 서비스가 다운되면 어떻게 할 것인가?
지금 발견하는 모든 위험은 마감 전날 밤 11시에 해결해야 할 문제가 아니라는 점에서 큰 이득이다.
💡 실제 사례: 첫 API 작업을 2일로 추정했지만, 인증·페이징·레거시 스키마를 묻지 않아 5일이 걸렸다. 위험 식별 30분이 3일의 놀라움을 막았다.
4️⃣ 계약서(Contract) 작성 (엔드포인트당 10분)
계약서는 코드가 아니다. 간단한 문서—Markdown, Notion 페이지, 화이트보드 사진—로 각 엔드포인트가 받는 입력과 반환값을 정의한다.
예시: POST /tasks
Description
새로운 작업을 생성하고 프로젝트에 할당한다.
Request Body
{
"title": "string (required, max 200 chars)",
"description": "string (optional)",
"projectId": "uuid (required)",
"assigneeId": "uuid (optional)",
"dueDate": "ISO date string (optional)"
}Success Response (201)
{
"status": "success",
"data": {
"id": "uuid",
"title": "string",
"status": "todo",
"createdAt": "timestamp"
}
}Error Cases
400→ 필수 필드 누락404→projectId를 찾을 수 없음403→ 사용자가 해당 프로젝트에 접근 권한이 없음
이 정도면 엔드포인트당 약 10분이면 작성 가능하다.
즉시 얻는 이점: 프론트엔드 동료가 당일에 목업 응답을 만들 수 있어 백엔드가 끝날 때까지 기다릴 필요가 없어진다. 이제 당신은 더 이상 블로커가 아니다.
코드를 실제로 작성할 때는 무엇을 만들지 정확히 알고 있기 때문에 결정 피로도와 모호함이 사라진다.
💡 프로 팁: 코딩을 시작하기 전에 이 계약서를 프론트엔드 개발자에게 보여라. “그게 아니에요”라는 피드백을 지금 받는 것이, 배포 후에 발견하는 것보다 훨씬 낫다.
많은 튜토리얼이 이 단계를 언급하지 않지만, 팀에서 잘 협업하는 개발자와 그렇지 않은 개발자를 가르는 핵심이다.
5️⃣ 정렬(Align) – 누군가에게 보여주기 (15분)
코드 한 줄을 쓰기 전, 계약서와 범위 문서를 누군가에게 보여준다.
물어볼 질문들
시니어 엔지니어 / 테크 리드에게
- “이 접근 방식이 괜찮나요? 놓친 부분이 있나요?”
- “코드베이스에 따라야 할 패턴이 있나요?”
- “제가 생각하지 못한 위험이 있나요?”
프론트엔드 개발자에게 (있다면)
- “이 응답 구조가 여러분이 만들고 있는 것에 맞나요?”
- “여기에 없는, 필요한 것이 있나요?”
자신에게 (진지하게 적어두기)
- “2분 안에 누군가에게 설명할 수 있나요?”
- “내일 내가 아프면 다른 사람이 이어받을 수 있나요?”
코드 작성 전 “내가 올바르게 생각하고 있나요?” 라는 질문은 약점이 아니라, 팀 기반 소프트웨어를 만든다는 이해의 표시다.
예전엔 질문을 하면 주니어처럼 보인다고 생각했지만, 이제는 모두가 시작하기 전에 정렬하는 것이 가장 시니어스러운 행동이라고 믿는다.