[Spring] REST API란? - 개념, 설계 원칙, URI 규칙

목차

📅 진행기간: 2024년 2월 5일 ~ 2024년 9월 20일

⭐ 요약

---

• REST API의 개념과 REST 아키텍처의 6가지 제약 조건을 정리한다.
• REST API의 URI 설계 원칙과 HTTP 메서드 활용 방법을 학습한다.
• REST API의 응답 형식인 JSON의 구조를 이해한다.
• Spring Boot에서 @RestController를 활용하여 REST API를 구현하는 방법을 정리한다.

⭐ REST API란?

---

1. REST의 정의

REST(Representational State Transfer)는 웹의 창시자 중 한 명인 Roy Fielding이 2000년 논문에서 제안한 아키텍처 스타일이다. REST는 특정 기술이나 프로토콜이 아니라, 웹의 장점을 최대한 활용하기 위한 설계 원칙의 집합이다.

 

REST API는 이 REST 원칙을 따르는 API를 의미한다. HTTP 프로토콜을 기반으로 클라이언트와 서버가 데이터를 주고받는 인터페이스이다.

용어	의미
API (Application Programming Interface)	소프트웨어 간에 데이터를 주고받기 위한 인터페이스
REST API	REST 아키텍처 원칙을 따르는 API
RESTful API	REST 원칙을 충실하게 지킨 API. REST API와 같은 의미로 사용되기도 함

2. REST의 6가지 제약 조건

REST 아키텍처를 따르려면 아래 6가지 제약 조건을 만족해야 한다. 이 조건들을 모두 만족할 때 RESTful하다고 표현한다.

제약 조건	설명
클라이언트-서버 구조 (Client-Server)	클라이언트와 서버는 서로 독립적으로 존재한다. 클라이언트는 UI, 서버는 데이터 처리를 담당하며 서로의 내부 구조를 알 필요가 없다.
무상태성 (Stateless)	서버는 클라이언트의 상태를 저장하지 않는다. 각 요청은 그 자체로 완결되어야 하며, 필요한 모든 정보가 요청에 포함되어야 한다.
캐시 가능 (Cacheable)	서버의 응답은 캐시 가능 여부를 명시해야 한다. 클라이언트는 캐시를 활용하여 불필요한 요청을 줄일 수 있다.
균일한 인터페이스 (Uniform Interface)	URI, HTTP 메서드, 응답 형식 등이 일관된 규칙을 따른다. REST API의 가장 핵심적인 특징이다.
계층화 시스템 (Layered System)	클라이언트는 서버와 직접 연결되었는지, 중간 계층(로드 밸런서, 캐시 서버 등)을 통하는지 알 필요가 없다.
코드 온 디맨드 (Code on Demand, 선택)	서버가 클라이언트에 실행 가능한 코드(JavaScript 등)를 전달할 수 있다. 선택 사항이다.

⭐ REST API URI 설계 원칙

---

1. URI 설계 기본 원칙

REST API에서 URI(Uniform Resource Identifier)는 서버의 자원을 식별하는 주소이다. 올바른 URI 설계를 위해 아래 규칙을 따른다.

원칙	올바른 예	잘못된 예
URI는 명사로, 자원을 표현한다.	/users	/getUsers, /createUser
행위는 HTTP 메서드로 표현한다.	GET /users	/users/get
소문자를 사용한다.	/users/profile	/Users/Profile
하이픈(-)으로 단어를 구분한다.	/user-profile	/user_profile, /userProfile
마지막에 슬래시(/)를 붙이지 않는다.	/users/1	/users/1/
파일 확장자를 포함하지 않는다.	/users/1	/users/1.json

2. HTTP 메서드와 URI의 조합

REST API에서 같은 URI라도 HTTP 메서드에 따라 다른 동작을 수행한다. 예를 들어 게시글(posts) 자원에 대한 CRUD는 아래와 같이 설계한다.

HTTP 메서드	URI	동작	설명
GET	/posts	목록 조회	전체 게시글 목록을 반환한다.
GET	/posts/{id}	단건 조회	특정 게시글 하나를 반환한다.
POST	/posts	생성	새 게시글을 생성한다.
PUT	/posts/{id}	전체 수정	특정 게시글 전체를 수정한다.
PATCH	/posts/{id}	부분 수정	특정 게시글의 일부 필드를 수정한다.
DELETE	/posts/{id}	삭제	특정 게시글을 삭제한다.

⭐ REST API 응답 형식: JSON

---

1. JSON이란?

JSON(JavaScript Object Notation)은 REST API에서 가장 많이 사용하는 데이터 교환 형식이다. 사람이 읽기 쉽고 기계가 파싱하기도 쉬운 텍스트 기반 형식이다.

{
  "id": 1,
  "title": "REST API 정리",
  "content": "REST API는 HTTP를 활용한 아키텍처 스타일이다.",
  "author": {
    "id": 10,
    "name": "손민주"
  },
  "tags": ["Spring", "REST", "API"],
  "createdAt": "2024-04-01T10:00:00"
}

JSON 데이터 타입	예시
문자열 (String)	"name": "손민주"
숫자 (Number)	"age": 25
불리언 (Boolean)	"isActive": true
배열 (Array)	"tags": ["Java", "Spring"]
객체 (Object)	"author": {"id": 1, "name": "홍길동"}
null	"deletedAt": null

⭐ Spring Boot에서 REST API 구현

---

1. 주요 어노테이션

어노테이션	설명
@RestController	@Controller + @ResponseBody의 조합이다. 모든 메서드의 반환값이 자동으로 JSON으로 직렬화되어 응답 본문에 담긴다.
@RequestMapping	클래스 또는 메서드 레벨에서 URI를 매핑한다.
@GetMapping	GET 요청을 처리하는 메서드에 붙인다.
@PostMapping	POST 요청을 처리하는 메서드에 붙인다.
@PutMapping	PUT 요청을 처리하는 메서드에 붙인다.
@PatchMapping	PATCH 요청을 처리하는 메서드에 붙인다.
@DeleteMapping	DELETE 요청을 처리하는 메서드에 붙인다.
@PathVariable	URI 경로 변수를 메서드 파라미터로 바인딩한다. 예: /posts/{id}
@RequestBody	HTTP 요청 본문의 JSON 데이터를 Java 객체로 역직렬화한다.
@RequestParam	쿼리 파라미터를 메서드 파라미터로 바인딩한다. 예: /posts?page=1

2. REST API 구현 예시

아래는 게시글(Post) CRUD REST API를 Spring Boot로 구현한 예시이다.

@RestController
@RequestMapping("/api/posts")
public class PostController {

    // GET /api/posts - 게시글 전체 목록 조회
    @GetMapping
    public List getPosts() {
        // 전체 게시글 목록 반환
    }

    // GET /api/posts/{id} - 게시글 단건 조회
    @GetMapping("/{id}")
    public PostResponse getPost(@PathVariable Long id) {
        // id에 해당하는 게시글 반환
    }

    // POST /api/posts - 게시글 생성
    @PostMapping
    public ResponseEntity createPost(@RequestBody PostRequest request) {
        // 게시글 생성 후 201 Created 응답
        return ResponseEntity.status(HttpStatus.CREATED).body(response);
    }

    // PUT /api/posts/{id} - 게시글 전체 수정
    @PutMapping("/{id}")
    public PostResponse updatePost(
            @PathVariable Long id,
            @RequestBody PostRequest request) {
        // id에 해당하는 게시글 전체 수정
    }

    // DELETE /api/posts/{id} - 게시글 삭제
    @DeleteMapping("/{id}")
    public ResponseEntity deletePost(@PathVariable Long id) {
        // id에 해당하는 게시글 삭제 후 204 No Content 응답
        return ResponseEntity.noContent().build();
    }
}

 

3. ResponseEntity를 활용한 HTTP 상태 코드 반환

REST API에서는 단순히 데이터만 반환하는 것이 아니라, 적절한 HTTP 상태 코드를 함께 응답해야 한다. Spring Boot에서는 ResponseEntity를 활용한다.

// 200 OK - 조회 성공
return ResponseEntity.ok(data);

// 201 Created - 생성 성공
return ResponseEntity.status(HttpStatus.CREATED).body(data);

// 204 No Content - 삭제 성공 (응답 본문 없음)
return ResponseEntity.noContent().build();

// 400 Bad Request - 잘못된 요청
return ResponseEntity.badRequest().build();

// 404 Not Found - 리소스 없음
return ResponseEntity.notFound().build();

 

⭐ REST API vs 일반 API 비교

---

항목	일반 API (비RESTful)	REST API (RESTful)
URI 설계	/getUser, /deleteUser, /createPost	GET /users/{id}, DELETE /users/{id}, POST /posts
행위 표현	URI에 행위를 포함 (동사 사용)	HTTP 메서드로 행위를 표현 (URI는 명사)
응답 형식	XML, 텍스트 등 다양	주로 JSON 사용
상태 코드	대부분 200으로 통일하거나 불규칙하게 사용	HTTP 상태 코드를 의미에 맞게 정확히 사용

⭐ 후기

---

• REST API를 단순히 "HTTP로 데이터를 주고받는 것"으로만 알고 있었는데, 6가지 제약 조건을 만족해야 한다는 것을 제대로 이해했다. 특히 무상태성(Stateless)이 왜 중요한지, 그리고 이것이 세션 방식과 어떻게 다른지 이해하게 되었다.
• URI 설계 원칙이 생각보다 엄격하다는 것을 알았다. 지금까지 URI에 동사를 섞어 쓰는 경우가 많았는데, REST 원칙대로 명사 기반 URI와 HTTP 메서드의 조합으로 설계하는 습관을 들여야겠다.

⭐ 참고자료

---

1) Spring 공식 문서, "Spring Boot Reference Documentation", https://docs.spring.io/spring-boot/docs/current/reference/html/

2) MDN Web Docs, "HTTP 상태 코드", https://developer.mozilla.org/ko/docs/Web/HTTP/Status

3) MDN Web Docs, "HTTP 요청 메서드", https://developer.mozilla.org/ko/docs/Web/HTTP/Methods

 

이 글은 패스트캠퍼스의 백엔드 개발 캠프에서 공부한 내용을 작성한 것입니다.