[REST API] REST API에 대한 이해와 활용법

REST API는 현대 웹 개발에서 필수적인 기술로, HTTP 프로토콜을 기반으로 자원의 표현과 상태를 주고받는 방식이다. REST는 Representational State Transfer의 약자이며, 자원을 식별하고 전송하며 상태를 변경하는 규칙을 정의한다. 이번 포스팅에서는 REST의 개념, RESTful 서비스, HTTP 메서드, POSTMAN 활용, 다양한 응답 방식, 예외 처리, HATEOAS, 그리고 Swagger 사용법에 대해 자세히 설명한다.

 

 

1. REST API 개요

REST(Representational State Transfer)는 HTTP 프로토콜을 기반으로 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일이다. 자원(Resource)을 URI로 식별하고, 그 자원에 대한 행위는 HTTP 메서드로 구분한다. REST는 다음과 같은 규칙을 따른다.

• 자원 식별: URI를 통해 자원을 명시하며, 각 자원은 명확한 URI로 표현해야 한다.
  • 대문자 사용 지양: URI는 가독성을 위해 소문자로 작성하는 것이 좋다.
  • 동사 사용 지양: 자원에 대한 행위는 HTTP 메서드를 통해 표현하고, URI는 명사로 자원을 식별한다.
  • HTTP 메서드로 행위를 표현: GET, POST, PUT, DELETE와 같은 HTTP 메서드로 자원에 대한 행위를 표현한다.

 

2. HTTP 메서드와 RESTful 서비스

RESTful 서비스는 웹 서비스에서 클라이언트가 요청(Request)을 보내고 서버가 응답(Response)을 제공하는 방식으로 이루어진다. 자원의 표현을 주고받기 위해 HTTP 메서드를 사용하며, 각 메서드는 다음과 같은 역할을 한다.

• GET: 자원을 조회한다. (예: /users/1 - 특정 사용자 조회)
• POST: 자원을 생성한다. (예: /users - 새로운 사용자 생성)
• PUT: 자원을 수정한다. (예: /users/1 - 특정 사용자 정보 수정)
• DELETE: 자원을 삭제한다. (예: /users/1 - 특정 사용자 삭제)

이처럼 REST API는 각 자원을 CRUD(Create, Read, Update, Delete) 방식으로 처리할 수 있도록 한다. RESTful 서비스는 JSON이나 XML 형식으로 데이터를 주고받으며, 클라이언트와 서버 간의 상호작용을 단순화한다.

 

 

3. POSTMAN을 활용한 API 테스트

POSTMAN은 REST API 개발과 테스트를 돕는 툴이다. HTTP 요청을 보내고, 응답을 확인하고, 헤더나 바디 값을 설정할 수 있는 기능을 제공한다. POSTMAN을 통해 REST API를 쉽게 테스트하고 확인할 수 있다.

 

 

4. REST API 응답 방식

RESTful 웹 서비스는 요청에 대한 응답으로 다양한 형식의 데이터를 반환할 수 있다. Spring에서는 @RestController를 사용하여 JSON, 문자열, 객체 등의 다양한 형식으로 데이터를 응답할 수 있다.

 

4.1. 문자열 응답

문자열을 직접 반환하여 간단한 메시지를 응답한다.

@GetMapping("/hello")
public String helloworld() {
    return "hello world";
}

결과: hello world

 

4.2. 기본 자료형 응답

기본적인 정수나 실수 값을 반환할 수 있다.

@GetMapping("/random")
public int getRandomNumber() {
    return (int) (Math.random() * 10) + 1;
}

결과: 랜덤한 정수 값 반환

 

4.3. 객체(Object) 응답

객체를 반환하여 JSON 형태로 응답할 수 있다.

@GetMapping("/message")
public Message getMessage() {
    return new Message(200, "메세지를 응답합니다.");
}

결과: { "httpStatusCode": 200, "message": "메세지를 응답합니다." }

 

4.4. 리스트(List) 응답

리스트 형태로 여러 데이터를 반환할 수 있다.

@GetMapping("/list")
public List<String> getList() {
    return List.of("사과", "바나나", "복숭아");
}

결과: ["사과", "바나나", "복숭아"]

 

4.5. 맵(Map) 응답

맵 자료형을 반환하여 키-값 쌍으로 응답할 수 있다.

@GetMapping("/map")
public Map<Integer, String> getMap() {
    return Map.of(404, "페이지를 찾을 수 없습니다", 500, "개발자의 잘못입니다", 200, "정상 응답");
}

결과: { "404": "페이지를 찾을 수 없습니다", "500": "개발자의 잘못입니다", "200": "정상 응답" }

 

 

5. 예외 처리

ResponseEntity를 사용하여 HTTP 상태 코드와 함께 응답을 반환할 수 있다. 또한, @ExceptionHandler를 활용하여 특정 예외 상황에 대해 적절한 메시지를 반환하는 예외 처리를 구현한다.

예를 들어, UserNotFoundException이 발생했을 때 이를 처리하는 예외 핸들러를 작성할 수 있다.

@ExceptionHandler(UserNotFoundException.class)
public ResponseEntity<ErrorResponse> handleUserNotFoundException(UserNotFoundException e) {
    return new ResponseEntity<>(new ErrorResponse("ERROR_CODE_00000", "회원 정보 조회 실패", e.getMessage()), HttpStatus.NOT_FOUND);
}

위와 같은 예외 처리는 클라이언트에게 의미 있는 에러 메시지를 제공하여 문제를 해결할 수 있도록 돕는다.

 

 

6. HATEOAS(Hypermedia as the Engine of Application State)

HATEOAS는 REST API의 응답에 관련 링크를 포함하여 클라이언트가 다음에 수행할 작업을 알 수 있도록 하는 방식이다. RESTful 서비스에서 링크를 통해 API 탐색을 가능하게 하여 시스템 간의 상호작용을 더욱 효율적으로 만든다.

예를 들어, 사용자 목록을 조회할 때 각 사용자에 접근하기 위한 링크를 함께 제공할 수 있다.

@GetMapping("/users")
public ResponseEntity<ResponseMessage> findAllUsers() {
    List<EntityModel<UserDTO>> userWithRel = users.stream()
        .map(user -> EntityModel.of(user, linkTo(methodOn(HateoasTestController.class).findUserByNo(user.getNo())).withSelfRel()))
        .collect(Collectors.toList());

    ResponseMessage responseMessage = new ResponseMessage(200, "조회 성공", Map.of("users", userWithRel));
    return new ResponseEntity<>(responseMessage, HttpStatus.OK);
}

이와 같이 링크 정보를 포함하면 클라이언트가 필요한 다음 작업을 쉽게 찾을 수 있다.

 

 

7. Swagger를 활용한 API 문서 자동화

Swagger는 API 문서를 자동으로 생성해주는 도구로, REST API를 테스트하고 관리하는데 매우 유용하다. Spring에서는 Swagger 설정을 통해 브라우저에서 직접 API 요청을 시도해볼 수 있는 인터페이스를 제공한다.

 

Swagger 설정 예시

@Configuration
@EnableWebMvc
public class SwaggerConfig {
    @Bean
    public Docket swaggerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                  .consumes(Set.of("application/json;charset=UTF-8"))
                  .produces(Set.of("application/json;charset=UTF-8"))
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("com.example"))
                  .paths(PathSelectors.any())
                  .build()
                  .useDefaultResponseMessages(false);
    }
}

이 설정을 통해 개발자는 API 문서를 자동으로 관리할 수 있으며, 다른 개발자들과의 협업도 수월해진다.

 

 

8. 마무리

REST API는 현재의 웹 개발에서 기본적인 데이터 전송 방식이다. REST API 설계를 할 때는 HTTP 메서드를 통해 자원을 표현하고, 예외 처리를 포함하여 안전하고 명확한 응답을 제공하는 것이 중요하다. 추가적인 기능으로 Swagger와 HATEOAS를 활용하면 API의 사용성을 크게 향상시킬 수 있다.