[Java] REST API란? 자바로 이해하는 RESTful 설계 원칙

REST API란 무엇일까?

백엔드나 Java 웹 개발을 공부하다 보면 REST API, RESTful API라는 표현을 정말 자주 보게 됩니다. 특히 Spring Boot로 프로젝트를 시작하면 거의 기본처럼 등장하죠.

그런데 처음 접하면 이런 생각이 듭니다.

• API는 알겠는데 REST는 뭐지?
• URL만 예쁘게 만들면 RESTful한 걸까?
• GET, POST만 잘 쓰면 되는 걸까?

이번 글에서는 Java 기준으로 REST API가 무엇인지, 왜 쓰는지, 그리고 RESTful하게 설계할 때 어떤 원칙을 봐야 하는지를 쉽게 정리해보겠습니다.

---

1. API와 REST를 먼저 구분해보자

API란?

API(Application Programming Interface)는 프로그램끼리 대화하는 창구라고 보면 됩니다.

예를 들어,

• 프론트엔드가 회원 목록을 요청한다
• 모바일 앱이 주문 정보를 가져온다
• 외부 서비스가 결제 결과를 전달한다

이런 요청과 응답을 주고받는 약속이 바로 API입니다.

REST란?

REST(Representational State Transfer)는 웹의 구조를 잘 활용해서 자원을 다루는 설계 스타일입니다. 조금 어렵게 들리지만, 쉽게 말하면 아래 느낌에 가깝습니다.

URL은 자원(Resource)을 표현하고, 동작은 HTTP 메서드로 구분하자

즉, REST는 단순한 기술 이름이라기보다 API를 설계하는 방식에 가깝습니다.

728x90

2. REST API란?

REST API는 REST 원칙을 따르면서 만든 웹 API입니다.

예를 들어 회원 정보를 다룬다고 해보겠습니다.

• 회원 목록 조회 → GET /users
• 회원 단건 조회 → GET /users/1
• 회원 등록 → POST /users
• 회원 수정 → PUT /users/1
• 회원 삭제 → DELETE /users/1

이 구조를 보면 URL은 users라는 자원을 표현하고, 실제 동작은 GET, POST, PUT, DELETE 같은 HTTP 메서드가 담당합니다.

이게 REST API의 핵심 감각입니다.

---

3. 왜 REST API를 많이 사용할까?

REST API가 많이 쓰이는 이유는 구조가 단순하고 일관성이 좋기 때문입니다.

장점

• 역할이 명확하다
  • URL은 자원
  • HTTP 메서드는 행위
• 프론트엔드/백엔드 협업이 편하다
• 문서화와 유지보수가 쉬워진다
• Spring Boot 같은 Java 프레임워크와 궁합이 좋다

특히 팀 프로젝트에서는 설계 규칙이 일정해야 협업이 쉬워집니다. REST는 이런 측면에서 아주 실용적입니다.

---

4. 자원(Resource) 중심으로 생각해야 한다

RESTful 설계에서 가장 중요한 포인트는 기능 중심이 아니라 자원 중심으로 보는 것입니다.

나쁜 예시

• /getUserList
• /createUser
• /deleteUser

이런 식의 URL은 동작이 URL에 들어가 있습니다. 처음엔 직관적으로 보일 수 있지만, API가 많아질수록 규칙이 무너지고 중복도 심해집니다.

더 RESTful한 예시

• GET /users
• POST /users
• DELETE /users/1

이 구조는 훨씬 일관적입니다.

한 줄로 정리하면:

URL은 “무엇”이고, 메서드는 “무슨 행동”인지 담당한다

---

5. HTTP 메서드 의미를 맞게 써야 한다

REST API에서 URL만 예쁘게 만드는 것으로는 부족합니다. HTTP 메서드의 의미를 제대로 맞춰 쓰는 것도 중요합니다.

주요 메서드 정리

REST API 기본 메서드

URL은 자원, 메서드는 동작을 표현합니다

메서드	의미	예시	설명
GET	조회	`GET /users/1`	데이터를 읽어온다
POST	생성	`POST /users`	새 자원을 만든다
PUT	전체 수정	`PUT /users/1`	자원 전체를 교체하는 느낌
PATCH	부분 수정	`PATCH /users/1`	일부 필드만 수정할 때 적합
DELETE	삭제	`DELETE /users/1`	자원을 제거한다

---

6. Java Spring Boot로 보면 더 이해가 쉽다

Spring Boot에서는 REST API를 아래처럼 자주 작성합니다.

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping
    public List<UserResponse> getUsers() {
        return List.of();
    }

    @GetMapping("/{id}")
    public UserResponse getUser(@PathVariable Long id) {
        return new UserResponse(id, "Kim");
    }

    @PostMapping
    public void createUser(@RequestBody UserCreateRequest request) {
        // 사용자 생성 로직
    }

    @PatchMapping("/{id}")
    public void updateUser(@PathVariable Long id,
                           @RequestBody UserUpdateRequest request) {
        // 사용자 수정 로직
    }

    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) {
        // 사용자 삭제 로직
    }
}

이 코드에서 중요한 점은 아래와 같습니다.

• /users는 자원 경로
• @GetMapping, @PostMapping, @PatchMapping, @DeleteMapping이 행위를 표현
• Java 코드 구조와 REST 설계가 자연스럽게 연결됨

즉, Spring Boot가 REST API 설계와 잘 맞는 이유도 바로 여기에 있습니다.

---

7. RESTful 설계 원칙은 무엇을 봐야 할까?

“REST API”와 “RESTful API”는 비슷하지만, 보통 RESTful은 REST 원칙을 더 일관되게 잘 지킨 설계를 말할 때 씁니다.

실무에서는 아래 기준을 많이 봅니다.

7-1. URL에 동사를 남발하지 않는다

• 비권장: /getUsers, /updateUser, /removeUser
• 권장: /users, /users/{id}

7-2. 복수형 자원명을 일관되게 사용한다

• /user보다 /users
• /order보다 /orders

팀 내 규칙만 일관되면 되지만, 일반적으로 복수형이 많이 쓰입니다.

7-3. 상태코드를 의미 있게 반환한다

예를 들면:

• 200 OK : 정상 조회/수정
• 201 Created : 생성 성공
• 204 No Content : 삭제 성공, 응답 본문 없음
• 400 Bad Request : 잘못된 요청
• 404 Not Found : 자원을 찾지 못함
• 500 Internal Server Error : 서버 오류

RESTful한 API는 단순히 JSON만 보내는 게 아니라, HTTP 자체의 의미를 잘 살려야 합니다.

7-4. 계층 구조가 보이게 설계한다

예를 들어 댓글이 게시글에 속한다면:

• /posts/1/comments
• /posts/1/comments/10

이런 식으로 자원 관계가 드러나도록 표현할 수 있습니다.

7-5. 일관된 응답 형식을 유지한다

성공/실패 응답 구조가 매번 다르면 프론트엔드가 다루기 어렵습니다.

예를 들어 아래처럼 규칙을 둘 수 있습니다.

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Kim"
  },
  "message": "요청이 성공했습니다."
}

이런 응답 규칙은 REST의 필수 조건은 아니지만, 실무에서는 일관성이 유지보수성을 크게 높여줍니다.

---

8. REST API와 RESTful API를 구분하면?

실제로는 두 표현을 섞어서 쓰는 경우가 많습니다. 그래도 감각적으로 구분하면 아래처럼 이해할 수 있습니다.

• REST API: REST 방식으로 만든 API
• RESTful API: REST 원칙을 더 잘 지키고 일관성 있게 설계된 API

즉, 모든 REST API가 완벽하게 RESTful한 것은 아닐 수 있습니다.

---

9. 초보자가 자주 하는 실수

실수 1. URL에 행동을 다 넣는다

• /createOrder
• /cancelOrder
• /updateOrderStatus

이 방식은 기능이 늘수록 API가 복잡해집니다.

실수 2. GET으로 데이터를 수정한다

조회용 메서드인 GET은 부작용 없이 읽기 중심으로 써야 합니다. GET 요청으로 삭제나 수정이 일어나면 설계가 혼란스러워집니다.

실수 3. 상태코드를 무조건 200으로 보낸다

오류가 나도 200을 보내고 본문에만 실패라고 적어두면, 클라이언트와 서버 간 약속이 흐려집니다.

실수 4. 자원 설계보다 컨트롤러 메서드 개수만 늘린다

처음에는 빨리 개발되지만, 나중에는 API 규칙이 제각각이라 문서화와 유지보수가 매우 힘들어집니다.

---

10. 실무에서는 REST를 얼마나 엄격하게 지켜야 할까?

실무에서는 “REST 교과서 100점”보다 일관성과 협업 효율이 더 중요할 때가 많습니다.

예를 들어 완벽한 REST 원칙과 약간 거리가 있더라도, 팀 전체가 같은 방식으로 설계하고 문서화가 잘 되어 있다면 충분히 좋은 API일 수 있습니다.

중요한 건 아래입니다.

• 자원 중심인가?
• HTTP 메서드 의미를 맞게 쓰는가?
• 상태코드가 자연스러운가?
• 응답 규칙이 일관적인가?
• 팀원들이 예측 가능한가?

즉, RESTful 설계는 “멋있어 보이는 규칙”이 아니라 협업 가능한 API를 만드는 실전 기준이라고 보는 편이 좋습니다.

---

11. 한 번에 정리하는 핵심 요약

• API는 프로그램끼리 대화하는 인터페이스다
• REST는 웹 자원을 중심으로 API를 설계하는 스타일이다
• REST API는 URL로 자원을 표현하고 HTTP 메서드로 동작을 구분한다
• RESTful 설계는 자원명, 메서드, 상태코드, 응답 형식을 일관성 있게 맞추는 것이다
• Java에서는 특히 Spring Boot의 @RestController 구조로 이해하면 쉽다

---

마무리

Java 백엔드 개발에서 REST API는 거의 기본 문법처럼 등장합니다. 하지만 핵심은 복잡하지 않습니다.

자원은 URL로, 행동은 HTTP 메서드로, 의미는 상태코드로 표현하자

이 기준만 잘 잡아도 API 설계가 훨씬 깔끔해집니다. 특히 Spring Boot로 프로젝트를 진행할 때는 처음부터 RESTful 감각을 잡아두면 이후 유지보수와 협업에서 큰 차이가 납니다.

 

2026.03.19 - [IT/Spring] - [Spring Boot] GET, POST, PUT, PATCH, DELETE 차이와 CRUD 구현 방법