REST API 설계 원칙 정리 — 일관된 자원 중심 구조를 만드는 기준

작성자Hee 2026-03-10 조회수 39

REST API는 단순히 URL을 만드는 방식이 아니라, 자원(Resource)을 중심으로 시스템을 표현하는 설계 방식이다.
기능 중심으로 즉흥적으로 만들기 시작하면 엔드포인트 규칙이 흐트러지고, 유지보수 비용이 빠르게 증가한다.

실무에서 REST API 설계의 핵심은 “일관성”이다.
URI, HTTP 메서드, 상태 코드, 응답 구조를 일관되게 유지해야 프론트엔드와 백엔드 모두 예측 가능한 구조를 가질 수 있다.

1. 자원(Resource) 중심으로 설계

REST API는 동작이 아니라 자원을 기준으로 URI를 설계한다.
즉 “무엇을 할 것인가”보다 “무엇을 다루는가”가 먼저다.

예를 들어 게시글을 다룬다면 URI는 보통 다음처럼 설계한다.


GET    /posts
GET    /posts/123
POST   /posts
PUT    /posts/123
DELETE /posts/123

/getPost, /createPost처럼 동사 중심으로 만들기 시작하면 규칙이 깨지기 쉽다.
URI는 명사형 자원으로 통일하고, 동작은 HTTP 메서드로 구분하는 것이 기본이다.

2. HTTP 메서드의 의미를 지키기

REST API는 HTTP 메서드의 의미를 그대로 활용해야 한다.
메서드 의미가 흔들리면 API를 사용하는 쪽에서 혼란이 커진다.

GET — 조회
POST — 생성
PUT — 전체 수정
PATCH — 부분 수정
DELETE — 삭제

예를 들어 조회 API를 POST로 만들면 캐시, 로깅, 프록시 처리에서 불리해진다.
GET은 조회, POST는 생성이라는 기본 원칙은 가능하면 지키는 편이 좋다.

3. URI는 계층 구조를 명확하게

URI만 보고도 어떤 자원을 다루는지 이해할 수 있어야 한다.
관계가 있는 자원은 계층 구조로 표현한다.


GET /members/10/posts
GET /posts/123/comments

이 구조는 “회원 10의 게시글”, “게시글 123의 댓글”이라는 의미를 자연스럽게 드러낸다.
반대로 관계 없는 자원을 억지로 중첩시키면 URI가 길어지고 관리가 어려워진다.

flowchart TD A["/members"] B["/members/{id}"] C["/members/{id}/posts"] D["/posts/{id}/comments"] A --> B B --> C A --> D

4. 응답 형식은 일관되게 유지

REST API는 엔드포인트마다 응답 형식이 달라지면 사용성이 급격히 떨어진다.
성공 응답과 실패 응답 구조를 가능한 한 통일하는 것이 좋다.


{
  "ok": true,
  "data": {
    "id": 123,
    "title": "REST API 설계"
  }
}

에러 응답도 구조를 맞추는 편이 운영과 디버깅에 유리하다.


{
  "ok": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "title is required"
  }
}

응답 구조가 계속 바뀌면 프론트엔드에서 예외 처리가 늘어나고, API 문서도 신뢰하기 어려워진다.

5. 상태 코드는 의미에 맞게 사용

REST API는 상태 코드만으로도 결과를 어느 정도 설명할 수 있어야 한다.
모든 응답을 200으로 보내고 body에서만 성공/실패를 구분하면 의미가 약해진다.

200 OK — 정상 조회/수정
201 Created — 생성 완료
400 Bad Request — 잘못된 요청
401 Unauthorized — 인증 필요
403 Forbidden — 권한 없음
404 Not Found — 자원 없음
500 Internal Server Error — 서버 내부 오류

상태 코드를 의미에 맞게 사용하면 모니터링과 장애 분석도 쉬워진다.
특히 인증/인가 오류를 400으로 보내면 문제 구분이 어려워진다.

6. 필터, 정렬, 페이징은 쿼리스트링으로 분리

목록 조회에서 조건 검색, 정렬, 페이징은 쿼리스트링으로 표현하는 것이 일반적이다.


GET /posts?page=2&size=20&sort=created_at,desc&status=published

이렇게 하면 자원 자체는 유지하면서 조회 조건만 분리할 수 있다.
정렬 컬럼과 방향은 서버에서 화이트리스트로 제한하는 것이 안전하다.

7. 버전 관리 기준 정하기

API는 시간이 지나면 응답 구조나 정책이 바뀐다.
호환성이 깨질 가능성이 있으면 버전 전략을 먼저 정해 두는 편이 좋다.


/v1/posts
/v2/posts

버전 관리를 하지 않으면 기존 클라이언트와 신규 클라이언트를 동시에 지원하기 어려워진다.
특히 외부 공개 API라면 버전 정책이 더 중요하다.

8. 자주 발생하는 설계 문제

기능 중심 URI가 늘어나는 경우

/post/create, /post/delete, /post/update처럼 동사형 URI가 계속 늘어나면
REST 구조보다는 RPC 형태에 가까워진다.

이 경우 자원 기준으로 다시 정리해야 한다.
URI는 명사, 행위는 HTTP 메서드로 분리하는 것이 기준이다.

상태 변경을 GET으로 처리하는 경우

예를 들어 GET /posts/123/delete 같은 형태는 위험하다.
GET은 조회 전용이어야 하므로, 상태 변경은 DELETE나 POST/PATCH로 분리해야 한다.

응답 구조가 엔드포인트마다 다른 경우

어떤 API는 data, 어떤 API는 result, 어떤 API는 item을 쓰기 시작하면 프론트엔드 처리 비용이 증가한다.
응답 포맷 표준을 먼저 정해 두는 편이 좋다.

한 줄 요약

REST API 설계는 자원 중심 URI, HTTP 메서드 의미 유지, 일관된 응답 구조와 상태 코드 사용이 핵심이다. 기능 중심이 아니라 자원 중심으로 정리해야 유지보수 가능한 API 구조가 된다.