Backend

REST API 설계 모범 사례 2026

한 줄 요약: 좋은 REST API는 리소스 중심 URL, 올바른 HTTP 메서드, 일관된 응답 형식, 버전 관리의 4가지 원칙을 따른다. REST API는 웹 서비스의 사실상 표준이다. 좋은 API URL의 원칙: 명사 사용 (/users, /orders), 복수형 (/users, not /user), 계층 관계 표현 (/users/123/orders), 동사 대신 HTTP 메서드 (GET/POST/PUT/DELETE).

by Lee발행: 2026-04-09

한 줄 요약: 좋은 REST API는 리소스 중심 URL, 올바른 HTTP 메서드, 일관된 응답 형식, 버전 관리의 4가지 원칙을 따른다.

REST API는 웹 서비스의 사실상 표준이다. 이 가이드는 실무에서 자주 실수하는 패턴과 모범 사례를 정리한다. 설계 시 한 번 잘못 정하면 하위 호환성 때문에 수정이 어렵기 때문에 처음부터 올바르게 설계해야 한다.

URL 설계 원칙

좋은 API URL의 원칙: 명사 사용(/users, /orders), 복수형(/users, not /user), 계층 관계 표현(/users/123/orders), 동사 대신 HTTP 메서드(GET/POST/PUT/DELETE).

리소스 중심 URL: /getUsers 대신 /users, /createPost 대신 POST /posts. URL은 명사(리소스)로 구성하고, 동작은 HTTP 메서드(GET/POST/PUT/PATCH/DELETE)로 표현한다. 중첩 리소스는 /users/123/posts처럼 계층적으로 표현한다.

REST API URL 설계 예시
# 좋은 설계
GET    /api/v1/users          # 목록
GET    /api/v1/users/123      # 상세
POST   /api/v1/users          # 생성
PATCH  /api/v1/users/123      # 부분 수정
DELETE /api/v1/users/123      # 삭제
GET    /api/v1/users/123/posts # 사용자의 포스트

# 나쁜 설계
GET    /api/getUser?id=123
POST   /api/deleteUser

일관된 응답 형식: 성공과 에러 모두 같은 구조를 사용한다. 에러 응답에는 HTTP 상태 코드와 함께 구체적인 에러 코드와 메시지를 포함한다. 페이지네이션은 ?page=2&limit=20 또는 커서 기반(?cursor=xxx&limit=20)으로 제공한다.

에러 처리 표준화

일관된 에러 응답 형식: HTTP 상태 코드(400, 401, 404, 500 등) + 에러 코드(앱 고유) + 사용자 메시지 + 상세 정보(개발 환경에서만).

페이지네이션과 필터링

대량 데이터 처리: 커서 기반 페이지네이션(offset보다 안정적), 필터(?status=active), 정렬(?sort=-created_at), 필드 선택(?fields=id,name).

API 버전 관리

URL 기반(/api/v1/)이 가장 명확하고 널리 사용된다. 헤더 기반(Accept: application/vnd.api+json;version=1)도 옵션이지만 디버깅이 불편하다. breaking change가 있을 때만 버전을 올리고, 이전 버전은 최소 6~12개월 동안 유지한다.

API 보안 체크리스트

HTTPS 필수, 인증(JWT/API Key), Rate Limiting(사용자당 분당 60회), 입력 검증(Zod/Joi), CORS 설정, SQL Injection 방어(ORM/Prepared Statement), 민감 데이터 필터링(비밀번호 해시를 응답에 포함하지 않기), 로그에 PII 제외.

문서화 팁: OpenAPI(Swagger) 스펙을 먼저 작성하고 코드를 생성하는 'API First' 접근이 가장 효율적이다. swagger-jsdoc이나 Fastify의 자동 스키마 생성으로 코드와 문서를 동기화하라.

1인 개발자 관점에서 이 주제가 왜 중요한가

이 글의 주제(REST API 설계 모범 사례 2026)를 다룰 때 저는 슈퍼베이스 + 버셀 + 카프카 조합으로 1인 백엔드를 굴리는 입장 관점에서 봅니다. 단순히 새 기능을 소개하는 입장이 아니라, 12개 한국어 사이트를 1인으로 운영하면서 매일 클로드 코드를 켜두고 작업하는 입장이라 의사결정의 기준이 다소 좁고 실용적인 편입니다. 신기술이 출시될 때마다 곧바로 도입하기보다는 우선 한두 사이트에 시범 도입해 두고, 운영 부담이 늘지 않는지 며칠 지켜본 뒤 전체 확산을 결정하는 식입니다.

가장 자주 보는 변수는 12개 사이트를 동시에 운영할 때 변수 분리 비용, 그리고 한국어 응답 품질의 미세한 한계입니다. 두 변수는 신기술을 도입할지 말지 결정할 때 거의 매번 영향을 줍니다. 글의 본문은 위의 두 축을 직접 명시하지는 않지만, 본문에서 다루는 항목을 이 축에 비춰 보시면 본인 환경에 맞는지 빠르게 판단할 수 있습니다. 특히 한국 결제 시 VAT 10% 환급 절차 같은 운영 변수는 도구 자체 성능보다 더 큰 영향을 주는 경우가 많기 때문에 본문 비교표를 볼 때 같이 떠올리시면 좋습니다.

한 가지 더 강조하면, Backend 영역의 글을 읽을 때 저는 본문이 다루는 도구·서비스가 ① 한국 결제 가능 여부 ② 한국어 응답 품질 ③ 종량제 비용의 예측 가능성 ④ 1인 개발자 학습 시간 대비 효과, 네 항목을 모두 충족해야 실제 도입을 결정합니다. 네 항목 중 하나라도 명확하지 않으면 도입을 1~2주 미루는 편이고, 그 사이 같은 카테고리의 다른 글도 확인합니다.

본문의 각 비교·코드·체크리스트는 이 네 항목 중 어느 부분에 영향을 주는지 의식하면서 보시면 더 빠르게 결론에 도달하실 수 있습니다. 본 사이트의 다른 Backend 글과 함께 보시면 같은 평가 축이 반복되는 것을 확인하실 수 있습니다. 토픽 페이지 또는 같은 카테고리 태그를 따라가시면 동일한 평가 기준이 적용된 글을 한 번에 모아 보실 수 있습니다.

본인 환경에 적용하기 전 확인할 체크포인트

본문의 내용을 본인 환경에 적용하기 전에 다음 항목을 빠르게 확인하시면 도입 실패 가능성을 줄일 수 있습니다.

공식 문서 버전 일치 — 본문 작성 시점과 현재 배포 버전이 다른 경우, 같은 명령어가 다르게 동작할 수 있습니다.
한국 결제·환율 검증 — 카드 결제, 부가가치세 처리, 원화 환산 시점에 따라 실제 청구액이 본문 예시와 다를 수 있습니다.
기존 스택과의 호환성 — Next.js·Vercel·Supabase 같은 기본 스택과 충돌이 없는지 패키지 의존성을 먼저 확인하세요.
롤백 절차 사전 정리 — 도입 후 문제가 생겼을 때 1회 명령으로 이전 상태로 되돌릴 수 있는 절차를 도입 전에 메모해 두시면 운영 부담이 크게 줄어듭니다.

위 네 항목을 모두 통과하면 보통 1~2시간 내에 도입을 마칠 수 있고, 통과하지 못한 항목이 있다면 그 항목을 우선 해결한 뒤 다시 시작하는 것이 효율적입니다.

자주 묻는 질문

다른 대안과 비교했을 때 어떤 상황에 적합한가요?

REST는 리소스가 명확하고 캐싱·표준 HTTP 메서드의 이점이 큰 공개 API나 일반적인 CRUD 서비스에 가장 적합합니다. URL이 곧 리소스라 직관적이고, 브라우저·CDN 캐시와 잘 맞으며 클라이언트가 다양할 때 진입 장벽이 낮습니다. 다만 모든 상황에 최선은 아닙니다. 화면마다 필요한 필드가 제각각이고 과다·과소 응답(over/under-fetching)이 문제라면 GraphQL이, 마이크로서비스 간 저지연 내부 통신이라면 gRPC가 더 적합합니다. 서버가 클라이언트로 계속 데이터를 밀어야 하는 실시간이라면 WebSocket이나 SSE를 함께 써야 하고요. 즉 외부에 공개하는 표준 API·CRUD 중심이면 REST, 복잡한 데이터 그래프나 고성능 내부 통신·실시간이면 다른 스타일을 검토하시면 됩니다.

더 깊게 공부하려면 어떤 자료를 보면 좋을까요?

표준부터 잡고 싶다면 HTTP 상태 코드의 의미를 정리한 RFC 9110(HTTP Semantics)과 에러 응답 표준인 RFC 9457(Problem Details for HTTP APIs)을 추천합니다. 본문에서 다룬 일관된 에러 형식을 어떻게 표준에 맞출지 바로 답이 나옵니다. 설계·문서화 실무는 OpenAPI(Swagger) 스펙 문서를 보면서 본문의 API First 접근을 직접 익히는 게 가장 빠르고, Zod나 Joi 문서로 입력 검증을 붙이면 보안 체크리스트까지 연결됩니다. 더 넓게 보려면 Microsoft REST API Guidelines나 Google API Design Guide 같은 대형 기업의 공개 가이드가 페이지네이션·버전 관리·네이밍 규칙의 실전 레퍼런스로 유용합니다.

REST API 설계 모범 사례 2026, 한 줄로 정리하면 어떻게 되나요?

좋은 REST API는 명사 복수형 리소스 URL(/users), 올바른 HTTP 메서드(GET·POST·PATCH·DELETE), 성공·에러가 같은 일관된 응답 형식, 그리고 /api/v1 같은 버전 관리 이 네 가지 원칙으로 요약됩니다. 핵심은 URL 규칙과 응답 봉투를 코드 한 줄 짜기 전에 못박는 것입니다. 한 번 잘못 정하면 모든 클라이언트가 묶여 하위 호환 때문에 바꾸기 어렵기 때문이고, 여기에 커서 기반 페이지네이션과 HTTPS·인증·Rate Limiting 같은 보안 기본을 더하면 설계의 큰 그림은 끝납니다.

실무에서 처음 도입할 때 가장 먼저 확인할 것은 무엇인가요?

URL 규칙부터 못박고 시작하시길 권합니다. 동사형 엔드포인트(/getUsers, /createPost)를 명사 복수형 리소스(/users)로 통일하고, 동작은 GET/POST/PATCH/DELETE 메서드로만 표현하는 것이 첫 단추입니다. 그다음 응답 봉투(성공·에러 동일 구조)와 에러 코드 체계를 먼저 합의해야 합니다. 이 둘은 나중에 바꾸면 모든 클라이언트가 깨지니, 코드 한 줄 짜기 전에 /api/v1/ 같은 버전 프리픽스까지 포함해 정해두는 편이 안전합니다.

가장 자주 발생하는 실수나 함정은 무엇인가요?

가장 흔한 함정은 URL에 동작을 동사로 박아넣는 것입니다. DELETE /api/deleteUser 처럼 메서드와 동사가 중복되면 캐싱·권한 규칙이 꼬입니다. 그다음은 페이지네이션을 offset 방식으로 시작했다가 데이터가 늘면서 깊은 페이지에서 느려지고 중복·누락이 생기는 경우인데, 본문 예시처럼 커서 기반(?cursor=xxx&limit=20)으로 가면 피할 수 있습니다. 마지막은 breaking change인데도 버전을 안 올려 기존 클라이언트를 깨뜨리는 것으로, /api/v1을 유지한 채 v2를 따로 열고 구버전을 6~12개월 병행하면 됩니다.

apirest설계백엔드패턴