[백엔드]RESTful API 이해하기

1. REST란?

REST의 개념

REST(Representational State Transfer)는 웹에서 데이터를 교환하는 아키텍처 스타일로, 리소스(Resource)를 정의하고 해당 리소스를 접근하는 방식을 규정합니다.

REST는 클라이언트와 서버 간의 통신을 간결하게 만들며, 웹의 기본 원칙을 준수하면서 API 설계를 단순화하는 방식입니다.

RESTful API란?

RESTful API는 REST의 원칙을 따르는 API를 의미합니다. HTTP 프로토콜을 기반으로 동작하며, 클라이언트가 서버의 특정 리소스를 요청하고 응답을 받는 구조를 가집니다.

---

2. RESTful API 설계 원칙

RESTful API를 설계할 때 따르는 기본 원칙은 다음과 같습니다.

1) 리소스 중심의 URL 설계

• RESTful API는 리소스(Resource) 를 중심으로 URL을 설계합니다.
• URL은 동사를 포함하지 않고, 명사를 사용하여 리소스를 나타냅니다.
• 예를 들어, 사용자 정보를 가져오는 API는 다음과 같이 정의합니다.
  • GET /users → 모든 사용자 조회
  • GET /users/{id} → 특정 사용자 조회
  • POST /users → 새로운 사용자 생성
  • PUT /users/{id} → 특정 사용자 정보 업데이트
  • DELETE /users/{id} → 특정 사용자 삭제

2) HTTP 메서드 활용

RESTful API에서는 HTTP 메서드를 적절히 활용합니다.

HTTP 메서드 설명

GET	리소스 조회
POST	리소스 생성
PUT	리소스 전체 수정
PATCH	리소스 부분 수정
DELETE	리소스 삭제

예를 들어, 특정 사용자의 정보를 가져오려면 GET /users/{id}를 호출하면 됩니다.

3) 상태 코드(Status Code) 활용

API 응답에는 적절한 HTTP 상태 코드를 포함해야 합니다. 대표적인 상태 코드는 다음과 같습니다.

상태 코드 의미

200 OK	정상적인 응답
201 Created	리소스 생성 성공
400 Bad Request	잘못된 요청
401 Unauthorized	인증 실패
403 Forbidden	권한 없음
404 Not Found	리소스 없음
500 Internal Server Error	서버 내부 오류

4) HATEOAS (Hypermedia as the Engine of Application State)

HATEOAS는 REST API의 중요한 개념 중 하나로, 응답에 링크 정보를 포함하여 클라이언트가 추가적인 API 요청을 쉽게 할 수 있도록 하는 방식입니다.

예를 들어, 사용자 정보를 조회할 때 관련 리소스에 대한 링크를 제공하는 방식입니다.

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "links": {
    "self": "/users/1",
    "orders": "/users/1/orders"
  }
}

---

3. RESTful API와 JSON 데이터 통신

RESTful API에서는 주로 JSON(JavaScript Object Notation) 형식을 사용하여 데이터를 주고받습니다.

요청(Request) 예제

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Alice",
  "email": "alice@example.com"
}

응답(Response) 예제

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 2,
  "name": "Alice",
  "email": "alice@example.com",
  "created_at": "2025-02-10T12:34:56Z"
}

응답 데이터는 표준화된 형식을 유지하는 것이 좋습니다.

API 응답 표준화 예시

{
  "status": "success",
  "message": "User created successfully",
  "data": {
    "id": 2,
    "name": "Alice",
    "email": "alice@example.com"
  }
}

---

4. RESTful API 구현 예제 (Spring Boot)

Spring Boot를 활용하여 간단한 RESTful API를 구현하는 예제를 살펴보겠습니다.

1) REST 컨트롤러 생성

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

    private final UserService userService;

    @Autowired
    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        User user = userService.getUserById(id);
        return ResponseEntity.ok(user);
    }
}

2) DTO(Data Transfer Object) 활용

public class UserDto {
    private Long id;
    private String name;
    private String email;
    // Getter, Setter 생략
}

3) 예외 처리

@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<String> handleUserNotFoundException(UserNotFoundException e) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(e.getMessage());
    }
}

---

결론

RESTful API는 현대적인 웹 애플리케이션에서 핵심적인 역할을 하는 아키텍처 스타일입니다. 잘 설계된 RESTful API는 확장성이 높고 유지보수가 쉬우며, 다양한 클라이언트와 원활하게 상호작용할 수 있습니다. 이 글에서는 REST의 기본 개념부터 API 설계 원칙, JSON 데이터 통신, 그리고 Spring Boot를 활용한 구현 예제까지 살펴보았습니다.

백엔드 개발을 하면서 RESTful API를 직접 구현해보고, 더 나아가 GraphQL과 같은 대체 기술도 비교해보면 더욱 깊이 있는 이해를 할 수 있을 것입니다. 🚀