출처. 짧고 굵게 배우는 JSP 웹 프로그래밍과 스프링 프레임워크 p124
스프링부트3 백엔드 개발자 되기 [자바편] p168
웹 개발자 모집 공고에서 자주 보게 되는 문구들...
🗨️ "Java Springboot 기반 RESTful API를 설계·개발해보신 분"
🗨️ "API 통신을 활용한 데이터 처리 경험 (RESTful API, GraphQL 등)"
🗨️ "Web API (RESTful API) 개발"
🗨️ "상용에서 RESTful API 혹은 GraphQL을 설계한 경험이 있는 분"
웹 개발자 과정 61일차 Spring Framework에서 비동기 요청을 배우며, 이론적으로 잠깐 다룬 RESTful API의 개념을 다시 정리해보려고 한다.
📕 RESTful API란?
RESTful API는 "Representational State Transfer"의 약자로, 자원의 상태를 주고받는 방식의 API다. 쉽게 말하면, REST API는 URL을 기반으로 자원을 정의하고, HTTP 메서드(예: GET, POST, PUT, DELETE)를 사용해 자원의 상태를 조작하는 방법이다.
RESTful API의 주요 특징
- 서버/클라이언트 구조
클라이언트와 서버가 독립적으로 동작하며, 서버는 데이터를 처리하고 클라이언트는 데이터를 표시하는 역할을 한다. - 무상태
각 요청은 독립적이고 상태를 저장하지 않는다. 즉, 서버는 요청 간의 상태를 기억하지 않으며, 모든 정보는 클라이언트에서 제공되어야 한다. - 캐시 처리 기능
HTTP 프로토콜을 활용하여 서버에서 보낸 응답을 캐시할 수 있어 성능을 향상시킬 수 있다. - 계층화
여러 계층으로 서버가 분리될 수 있어, 클라이언트가 서버의 특정 세부 구현에 의존하지 않도록 만든다. - 인터페이스 일관성
URL 설계 및 HTTP 메서드 사용에 있어 일관성을 유지하여, API의 직관성을 높이고 개발자가 쉽게 이해할 수 있도록 돕는다.
RESTful API의 장점과 단점
장점
직관적인 URL 설계: URL만 보고도 해당 API가 무엇을 하는지 쉽게 파악할 수 있다.클라이언트-서버 분리: 클라이언트와 서버의 역할이 명확히 분리되어, 유지보수와 확장이 용이하다.플랫폼 독립성: HTTP 표준을 따르므로 다양한 플랫폼에서 사용할 수 있다.
단점
제한된 HTTP 메서드: HTTP 메서드(GET, POST 등)에 의존하기 때문에 유연성이 제한될 수 있다.명확한 표준 부재: REST API 설계를 위한 공식적인 규약이 없어서, 설계자가 정의하는 방식에 따라 일관성이 부족할 수 있다.
그럼에도 불구하고 RESTful API는 URL과 메서드만으로 요청 내용을 파악할 수 있는 강력한 장점 덕분에 널리 사용되고 있다.
RESTful API를 사용하는 방법
규칙 1. URL에는 동사를 사용하지 않는다
URL에서는 자원의 이름만을 사용하고, 자원에 대해 어떤 행동을 할지를 나타내는 동사는 사용하지 않는다.
예를 들어, 잘못된 설계는 다음과 같다:
/getUser/123 (동사 get 사용)
/showUser/123 (동사 show 사용)
이렇게 동사를 사용하면 API 사용자가 혼란스러워할 수 있다.
올바른 설계는 이렇게 해야 한다:
/users/123
users는 자원을 나타내고, 123은 특정 사용자 ID를 나타낸다.
규칙 2. 동사는 HTTP 메서드로 해결한다
자원에 대해 어떤 작업을 할지는 HTTP 메서드로 해결한다.
GET(조회): 서버에서 데이터를 조회할 때 사용.
예시: GET /users/123 → 123번 사용자의 정보를 조회.POST(생성): 새로운 자원을 서버에 생성할 때 사용.
예시: POST /users → 새 사용자 정보를 생성.PUT(수정): 기존 자원을 업데이트할 때 사용.
예시: PUT /users/123 → 123번 사용자의 정보를 수정.DELETE(삭제): 자원을 삭제할 때 사용.
예시: DELETE /users/123 → 123번 사용자를 삭제.
URL 설계 규칙
이외에도 아래와 같은 규칙도 존재한다.
슬래시("/")는 자원 간의 계층 관계를 나타낸다.
예를 들어, /users/123/posts는 특정 사용자가 작성한 게시물을 의미한다.
즉, users는 부모 자원이고, posts는 그 하위 자원이다.
하이픈(-)과 밑줄(_)은 자원 이름에 가독성을 높이기 위해 사용된다.
RESTful API에서는 하이픈을 사용하는 것이 일반적이다.
잘못된 예: /user_profiles
올바른 예: /user-profiles
단수와 복수 : 컬렉션 자원은 복수형으로, 개별 자원은 단수형으로 사용한다.
복수형: /users → 사용자 목록을 의미.
단수형: /users/123 → 123번 사용자를 의미.
RESTful API를 설계하는 규칙은 이정도가 있다. 다만, 명확히 정의된 표준이라기보단 업계에서 일반적으로 따른느 관례라고 볼 수 있다. 공식적인 규격은 아니지만 많은 개발자들이 공유하는 약속인 것이다.
이러한 규칙들은 REST의 기본 원칙(자원을 URL로 정의하고, HTTP 메서드를 통해 자원에 대한 작업을 수행하는 아키텍처 스타일)을 따르며, API가 일관성 있고 직관적이며 유지보수하기 쉬운 형태로 설계될 수 있도록 도와준다.
📍 규칙에 맞게 예전 프로젝트에서 내가 만든 리뷰 시스템의 URL을 수정해보았다.
📋 이전 코드
@PostMapping("/register")
public String register(@RequestParam("content") String content, @RequestParam("rating") double rating, ...){
// 리뷰 등록 메서드
}
@GetMapping("/list/{prno}/{pageNo}/{mno}")
public ReviewPagingDTO getList(@PathVariable("prno") long prno, ...){
// 리뷰 목록 출력 메서드
}
@GetMapping("/delete/{rno}")
public String delete(@PathVariable("rno") long rno){
// 리뷰 삭제 메서드
}🛠️ 개선된 코드
// 리뷰 등록
@PostMapping("/reviews")
public String createReview(@RequestBody ReviewVO reviewVO){
// 리뷰 등록 메서드
}
// 리뷰 목록 조회
@GetMapping("/reviews/{prno}")
public ReviewPagingDTO getReviews(@PathVariable("prno") long prno, @RequestParam("page") int page){
// 리뷰 목록 출력 메서드
}
// 리뷰 삭제
@DeleteMapping("/reviews/{rno}")
public String deleteReview(@PathVariable("rno") long rno){
// 리뷰 삭제 메서드
}이렇게 동사를 제거하고 HTTP 메서드를 활용해 의도를 명확히 표현해보았다. 이전 프로젝트에서는 바빠서라는 이유로 RESTful API에 대해서 크게 규칙을 생각하지 않았는데, 새로 하게될 프로젝트에서는 규칙을 명확하게 지키려 신경써야겠다는 다짐을 하게 되었다.
📌 정리
💬"RESTful API는 자원을 URL로 정의하고, HTTP 메서드(GET, POST, PUT, DELETE)를 통해 자원에 대한 작업을 수행하는 아키텍처 스타일입니다. 각 자원은 고유한 URL로 표현되며, HTTP 메서드를 사용해 자원에 대한 읽기, 생성, 수정, 삭제 작업을 구분합니다. 이 설계 방식은 직관적이고, 서버와 클라이언트 간의 역할을 명확하게 분리할 수 있어 협업과 유지보수가 용이합니다. 또한, 무상태성을 유지하여 각 요청이 독립적으로 처리되기 때문에 확장성도 높습니다. RESTful API는 간단하고 효율적이어서 많은 웹 서비스에서 널리 사용되고 있습니다."
