[Java] REST API 란? 쉽게 시작하기

REST API란?

REST(Representational State Transfer)는 웹에서 자원을 이름으로 구분하고 그 자원의 상태를 주고받는 아키텍처 스타일이에요. 쉽게 말해, HTTP 메서드(GET, POST, PUT, DELETE)를 이용해 서버 자원을 조작하는 방식을 뜻합니다

Java로 REST API를 개발할 때 가장 많이 쓰는 프레임워크는 Spring Boot입니다. 이 글에서도 Spring Boot를 중심으로 설명할게요.

Java REST API 개발, 쉽게 시작하기

먼저 Java REST API 개발에 대해 실무에 바로 적용할 수 있는 핵심 내용을 함께 살펴볼 거예요. 백엔드 개발자분들이라면 REST API는 필수 중의 필수죠. 하지만 막상 개발하려고 하면 "어디서부터 시작하지?", "이렇게 해도 괜찮은 걸까?" 하는 고민이 많을 텐데요. 그런 고민을 덜어드리고 싶어서 쉽고 짧게 풀어 설명해드릴게요.

핵심 개념: Spring Boot로 REST API 만들기

1. Controller 만들기

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

    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        // DB에서 사용자 정보를 조회하는 코드가 들어감
        return ResponseEntity.ok(user);
    }

    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        // 사용자 저장 로직
        return ResponseEntity.status(HttpStatus.CREATED).body(user);
    }
}

• @RestController는 JSON 형태로 결과를 반환하는 컨트롤러임을 뜻해요.
• @RequestMapping으로 기본 URL을 지정합니다.
• 각각의 HTTP 메서드(GET, POST 등)에 맞게 매핑해서 동작을 정의하죠.

2. DTO와 Entity 분리

실무에서는 요청과 응답에 사용할 DTO(Data Transfer Object)를 Entity와 분리하는 게 좋아요. 이렇게 하면 데이터 유효성 검증이나 API 스펙 변경 시 유연하게 대응할 수 있어요.

3. 예외 처리

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {
        ErrorResponse error = new ErrorResponse("NOT_FOUND", ex.getMessage());
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }

}

• API는 항상 예상치 못한 예외에 대비해야 해요.
• @ControllerAdvice와 @ExceptionHandler를 활용해 전역 예외 처리를 구현하면 깔끔한 에러 응답을 보낼 수 있습니다.

실무 적용 팁

• Swagger(OpenAPI)로 문서 자동화: API 문서는 개발자 간 소통에 필수입니다. Springdoc-openapi 라이브러리를 사용하면 코드만으로 문서를 쉽게 만들 수 있어요.

• Validation 꼭 하자: @Valid와 @NotNull, @Size 같은 애노테이션을 활용해 입력값을 검증해 주세요. 검증 실패 시 적절한 에러 메시지를 반환하는 것도 중요합니다.

• HTTP 상태 코드 신경 쓰기: 성공, 실패 상황에 맞는 HTTP 상태 코드를 꼭 반환하세요. 예를 들어, 생성 성공 시 201 Created, 요청이 잘못됐을 땐 400 Bad Request 등.

• 로그 남기기: 개발 중 문제를 빠르게 파악하려면 적절한 로그가 필요합니다. Spring AOP나 Interceptor를 활용해 요청과 응답 로그를 남겨 보세요.

흔히 하는 실수와 주의사항

• GET 메서드에 본문(Body)을 보내기: HTTP 표준에 맞지 않으니 피하세요.

• Exception을 무조건 단순히 던지기: 사용자에게 불필요한 정보가 노출될 수 있어요. 꼭 전역 예외 처리기로 관리하세요.

• API 버전 관리 안 하기: 실무에서는 API가 변경될 수 있으니 URL에 버전을 명시하는 게 좋습니다. 예: /api/v1/users

• CORS 설정 누락: 프론트엔드와 통신할 때 CORS 설정이 없으면 요청이 막힐 수 있습니다. 필요한 도메인에 대해 설정해 주세요. 주로 webConfig.java 파일을 통해 관리합니다.

마무리

REST API 개발은 처음엔 낯설어도 익숙해지면 오히려 쉽고 빠르게 개발이 가능해서 장점이 많습니다. 다음글에서는 더 자세한 예시로 돌아오겠습니당