RESTful API란? 개념부터 설계 원칙, 구현 정리

1. RESTful API란?

RESTful API는 REST(Representational State Transfer) 아키텍처 스타일을 따르는 API를 의미한다.

REST는 2000년 로이 필딩(Roy Fielding)이 논문에서 소개한 개념으로,

웹의 장점을 극대화하는 네트워크 아키텍처 원칙을 기반으로 한다.

RESTful API는 클라이언트와 서버 간의 통신을 REST의 원칙에 맞게 설계한 API를 의미한다.

쉽게 말해, RESTful API는 "규칙을 지키는 HTTP API"라고 볼 수 있다.

규칙을 따르지 않으면 RESTful하지 않은 API가 될 수 있다.

---

2. REST의 기본 원칙

RESTful API를 설계하기 위해서는 REST의 기본 원칙을 이해해야 한다.

REST는 다음과 같은 주요 원칙을 따른다.

1) 클라이언트-서버 구조 (Client-Server)

• 클라이언트와 서버는 서로 독립적으로 동작해야 한다.
• 클라이언트는 UI와 사용자 경험을 담당하고, 서버는 데이터 저장 및 비즈니스 로직을 처리한다.
• 서로의 역할이 명확하게 분리되어야 확장성과 유지보수성이 좋아진다.

2) 무상태성 (Stateless)

• 서버는 클라이언트의 상태를 저장하지 않는다.
• 각 요청은 독립적이며, 필요한 모든 정보를 요청에 포함해야 한다.
• 예를 들어, 로그인 상태를 유지하려면 클라이언트는 매 요청마다 인증 정보를 포함해야 한다.

3) 캐시 가능 (Cacheable)

• 클라이언트는 응답을 캐싱할 수 있어야 한다.
• 응답에는 캐싱 관련 정보를 담아야 하며, Cache-Control, ETag 등의 HTTP 헤더를 활용한다.
• 불필요한 서버 요청을 줄여 성능을 향상시킬 수 있다.

4) 계층화된 시스템 (Layered System)

• 클라이언트는 서버와 직접 통신하는 것이 아니라 **중간 계층(프록시, 로드 밸런서 등)**을 거칠 수 있다.
• 이를 통해 보안, 로드 밸런싱, 성능 최적화 등을 할 수 있다.

5) 일관된 인터페이스 (Uniform Interface)

• RESTful API는 일관된 방식으로 설계되어야 한다.
• 모든 리소스는 명사 기반 URL을 사용하고, HTTP 메서드를 일관성 있게 사용해야 한다.
• 예를 들어, GET /users는 사용자 목록을 조회하고, POST /users는 새로운 사용자를 추가한다.

6) 코드 온 디맨드 (Code on Demand, 선택 사항)

• 클라이언트가 실행할 수 있는 코드를 서버가 제공할 수 있다.
• 예를 들어, JavaScript 파일을 클라이언트로 전송하여 동적으로 실행하게 하는 방식이 가능하다.

위의 원칙 중 "코드 온 디맨드"는 필수 요소가 아니며, 나머지 다섯 가지는 반드시 지켜야 한다.

---

3. RESTful API 설계 원칙

RESTful API는 리소스를 중심으로 설계해야 한다. API에서 다루는 데이터는 "리소스(Resource)"이며,

이를 관리하기 위한 명확한 URL 및 HTTP 메서드를 정의하는 것이 중요하다.

1) 리소스를 기반으로 한 URL 설계

• 리소스는 명사를 사용하여 표현한다.
• URL 경로에는 동사가 포함되지 않는다.
• 예시:
  • GET /users (모든 사용자 조회)
  • GET /users/1 (ID가 1인 사용자 조회)
  • POST /users (새로운 사용자 생성)
  • PUT /users/1 (ID가 1인 사용자 정보 수정)
  • DELETE /users/1 (ID가 1인 사용자 삭제)

2) HTTP 메서드 활용

RESTful API에서는 HTTP 메서드를 일관되게 사용해야 한다.

HTTP 메서드의미예시

GET	데이터 조회	GET /users/1 (1번 사용자 조회)
POST	새로운 리소스 생성	POST /users (새 사용자 추가)
PUT	기존 리소스 전체 수정	PUT /users/1 (1번 사용자 정보 수정)
PATCH	기존 리소스 부분 수정	PATCH /users/1 (1번 사용자의 일부 정보 수정)
DELETE	리소스 삭제	DELETE /users/1 (1번 사용자 삭제)

3) 응답 상태 코드 사용

올바른 HTTP 상태 코드를 사용하면 API의 가독성이 좋아지고, 클라이언트가 응답을 쉽게 처리할 수 있다.

상태 코드의미

200 OK	정상 응답
201 Created	새로운 리소스 생성 성공
204 No Content	요청 성공, 하지만 반환할 데이터 없음
400 Bad Request	잘못된 요청 (유효성 검사 실패 등)
401 Unauthorized	인증 실패 (로그인 필요)
403 Forbidden	권한 없음
404 Not Found	리소스를 찾을 수 없음
500 Internal Server Error	서버 오류

---

4. RESTful API 예제 (Spring Boot)

아래는 Spring Boot를 활용한 RESTful API 예제이다.

1) REST 컨트롤러

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

    private final List<User> users = new ArrayList<>();

    // 사용자 목록 조회 (GET /users)
    @GetMapping
    public List<User> getUsers() {
        return users;
    }

    // 특정 사용자 조회 (GET /users/{id})
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable int id) {
        return users.stream()
                .filter(user -> user.getId() == id)
                .findFirst()
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }

    // 사용자 추가 (POST /users)
    @PostMapping
    public ResponseEntity<User> addUser(@RequestBody User user) {
        user.setId(users.size() + 1);
        users.add(user);
        return ResponseEntity.status(HttpStatus.CREATED).body(user);
    }

    // 사용자 정보 수정 (PUT /users/{id})
    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(@PathVariable int id, @RequestBody User newUser) {
        for (User user : users) {
            if (user.getId() == id) {
                user.setName(newUser.getName());
                user.setEmail(newUser.getEmail());
                return ResponseEntity.ok(user);
            }
        }
        return ResponseEntity.notFound().build();
    }

    // 사용자 삭제 (DELETE /users/{id})
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable int id) {
        if (users.removeIf(user -> user.getId() == id)) {
            return ResponseEntity.ok().build();
        }
        return ResponseEntity.notFound().build();
    }
}

2) User 모델

public class User {
    private int id;
    private String name;
    private String email;

    // Getter, Setter, 생성자 생략
}

---

5. 결론

RESTful API는 웹의 원칙을 따르는 HTTP API로,

리소스를 중심으로 URL을 설계하고 HTTP 메서드를 일관성 있게 사용해야 한다.

올바른 설계를 지키면 유지보수성과 확장성이 뛰어난 API를 만들 수 있다.

Spring Boot를 활용하면 RESTful API를 쉽게 구현할 수 있으며,

상태 코드와 JSON을 활용해 명확한 API 응답을 제공할 수 있다.