26.01.02 restfull 설계방식에 대해서 설명하고 이를 적용할 때 에매한 경우의 예시를 들어, 보통 이럴 때 어떻게 하는지를 설명해주세요.

1. RESTful의 3대 요소

REST API는 다음 3가지로 구성된다.

1. 자원 (Resource): 행위의 주체 (URI) -> 명사로 표현
2. 행위 (Verb): 수행하려는 작업 (HTTP Method) -> 동사 대신 메서드로 표현
3. 표현 (Representation): 주고받는 데이터 (JSON, XML 등)

 

2. 가장 중요한 설계 규칙 (Best Practices)

규칙 1: URI는 정보의 자원(명사)만 표현해야 한다.

URI에 get, delete, create 같은 동사가 들어가면 안 됩니다. 행위는 HTTP 메서드가 담당하기 때문이다.

• ❌ Bad (동사 포함):
  • GET /getMembers
  • POST /createMember
  • DELETE /deleteMember/1
• ✅ Good (명사만 사용):
  • GET /members (회원 목록 조회)
  • POST /members (회원 생성)
  • DELETE /members/1 (1번 회원 삭제)

 

규칙 2: 자원에 대한 행위는 HTTP Method로 표현한다.

가장 많이 사용하는 5가지 메서드를 용도에 맞게 써야 한다.

메서드	역할	SQL 매핑	특징
GET	조회	SELECT	데이터 변경 없음(안전)
POST	생성	INSERT	새로운 리소스 생성
PUT	전체 수정	UPDATE	데이터를 통째로 수정
PATCH	부분 수정	UPDATE	변경된 필드만 수정
DELETE	삭제	DELETE	리소스 삭제

 

규칙 3: 계층 관계는 슬래시(/)로 표현한다.

• 상황: "1번 유저가 키우는 강아지들 목록"을 보고 싶다.
  • GET /users/1/dogs
• 상황: "1번 유저가 키우는 강아지 중 2번 강아지 상세 정보"
  • GET /users/1/dogs/2

 

3. 적절한 상태 코드 (Status Code) 반환

RESTful API는 성공 여부를 HTTP 상태 코드로 명확히 알려줘야 한다. (무조건 200 OK만 보내면 안 된다.)

• 2xx (성공)
  • 200 OK: 요청 성공 (조회, 수정, 삭제 등)
  • 201 Created: 생성 성공 (POST 요청 시 주로 사용)
• 4xx (클라이언트 오류)
  • 400 Bad Request: 요청 파라미터가 틀림 (유효성 검사 실패 등)
  • 401 Unauthorized: 인증 안 됨 (로그인 필요)
  • 403 Forbidden: 권한 없음 (로그인은 했으나 접근 불가)
  • 404 Not Found: 자원 없음 (없는 페이지/데이터)
• 5xx (서버 오류)
  • 500 Internal Server Error: 서버 내부에서 에러 터짐 (NullPointerException 등)

 

4. RESTful API 설계 예시 (게시판)

'게시글(Article)'을 관리하는 API를 만든다면 이렇게 설계한다.

기능	HTTP Method	URI	설명
게시글 목록 조회	GET	/articles	모든 게시글을 가져옴
게시글 단건 조회	GET	/articles/{id}	id에 해당하는 게시글 하나만 가져옴
게시글 등록	POST	/articles	본문(Body)에 내용을 담아 등록
게시글 수정	PATCH	/articles/{id}	id 게시글의 내용 일부를 수정
게시글 삭제	DELETE	/articles/{id}	id 게시글을 삭제

 

5. 설계할 때 애매하다고 생각할 때

1. "동작"을 표현하기 애매할 때 (로그인, 초기화 등)

REST는 URI를 명사(자원)로 쓰라고 한다.

그런데 로그인(Login), 이메일 발송(Send), 초기화(Reset) 같은 명백한 동작은 어떻게 해야 할까?

• 난제: POST /users/login ? 이건 login이라는 동사가 들어가서 REST 원칙 위반이다.
• 교과서적 해결 (Purist): 모든 것을 '자원'으로 치환한다.
  • 로그인 -> 세션을 생성한다 -> POST /sessions
  • 송금 -> 이체 내역을 생성한다 -> POST /transfers
• 현실적 해결 (Pragmatic) - 추천:
  • 억지로 명사로 바꾸기 힘들면, 컨트롤 URI(Control URI)를 허용한다.
  • 자원 뒤에 동사를 붙여서 명확한 의도를 드러낸다.
  • 예: POST /users/1/activate (휴면 해제), POST /users/login (로그인)
  • Tip: 너무 얽매이지 말고, 동료들이 이해하기 쉬운 직관적인 경로를 택하자!

 

2. 복잡한 검색 조건 (GET vs POST)

REST에서 '조회'는 무조건 GET을 써야 합니다. 그런데 검색 조건이 너무 많거나 복잡하면 어떻게 할까?

• 난제: 검색 조건이 20개라서 URL이 너무 길어지거나, 보안상 URL에 노출되면 안 되는 정보가 검색 조건에 포함될 때.
  • GET /users?name=kim&age=20&region=seoul&job=dev&... (너무 길어서 잘림)
• 현실적 해결:
  • 이런 경우에는 예외적으로 POST를 사용한다.
  • 검색 조건을 URL 쿼리 파라미터가 아닌 Body(본문)에 담아서 보낸다.
  • URI는 보통 이렇게 한다: POST /users/search 또는 POST /users/filter
  • 원칙적으로 POST는 '생성'이지만, 실무에서는 '복잡한 데이터를 처리해줘'라는 의미로도 쓴다..

 

3. 관계가 너무 깊어질 때 (URI 깊이)

자원의 계층 구조를 표현하다 보면 URI가 끝도 없이 길어질 때가 있다.

• 난제: "1번 유저가 쓴 게시글 중, 5번 게시글에 달린 댓글 중, 3번 댓글"을 삭제하고 싶다.
  • DELETE /users/1/posts/5/comments/3 (너무 깁니다. 가독성 최악)
• 현실적 해결:
  • URI는 **최대 2 depth(단계)**까지만 들어가는 것을 권장한다.
  • comments의 ID(3번)가 유니크하다면, 굳이 앞의 경로가 필요 없다. 바로 접근하게 만든다.
  • 개선: DELETE /comments/3
  • Tip: 자원의 종속 관계가 필수적인 경우에만 계층을 만들고, ID만으로 식별 가능하면 바로 접근시키는 것이 좋다.

 

4. API가 변경되었을 때 (버전 관리)

앱을 출시했는데, API 설계를 바꿔야 한다.

그냥 바꾸면 기존 앱 사용자들이 다 에러가 발생할 것이다.

• 난제: REST 원칙에는 버전에 대한 명확한 규칙이 없다.
• 현실적 해결:
  • URI Versioning: 가장 직관적이고 많이 쓰는 방식이다. URI 맨 앞에 버전을 명시한다.
    • GET /v1/members (구버전)
    • GET /v2/members (신버전 - 응답 데이터 구조가 바뀜)
  • 이렇게 하면 서버에서는 v1 컨트롤러와 v2 컨트롤러를 따로 관리하여, 기존 사용자도 보호하고 새로운 기능도 배포할 수 있다.

 

6. 면접 답변식 요약

RESTful API는 HTTP 프로토콜을 의도에 맞게 사용하여 자원을 명확히 표현하는 설계 방식입니다.

핵심은 URI로 자원(Resource)을 명시하고, HTTP Method(GET, POST, PUT, DELETE)로 해당 자원에 대한 행위를 결정하는 것입니다. 이를 통해 API 명세서만 보고도 직관적으로 기능을 이해할 수 있게 되며, 클라이언트와 서버가 독립적으로 진화할 수 있는 유연성을 가집니다.