[spring] Spring Boot를 이용하여 RESTful API 개발(1) - RESTful API 설계 가이드 및 개발하기

RESTful API를 개발 하기 전 REST에 대해 궁금한 사람은 아래 포스팅을 참고하자.

2023.04.21 - [Web Application/Spring boot] - [spring] Spring Boot를 이용하여 RESTful API 개발(1) - REST, RESTful API에 대한 설명 및 REST의 제약조건과 장점

[spring] Spring Boot를 이용하여 RESTful API 개발(1) - REST, RESTful API에 대한 설명 및 REST의 제약조건과 장

 

RESTful API 설계

RESTful API를 설계하는 방법은 아래와 같다.

 

  ① URI 설계 : 리소스의 유형과 식별자를 포함한다.

//id를 식별자로 사용하는 사용자 리소스를 식별하는 URI
GET /users/{id}

 

 

      - URI는 리소스를 식별하는데 사용되며, API의 엔드포인트를 정의하는데 중요하다. 

      - URI는 일관된 패턴을 사용해야 하며, 일관성 있는 URI 패턴은 사용하는 클라이언트가 쉽게 이해하고 사용할 수 있도록 도와준다.

      - 리소스 명은 동사보다는 명사를 사용한다. 

 

  ② HTTP Method 선택

      - HTTP 메소드는 API에서 수행할 작업의 유형을 결정한다.

      - HTTP메소드는 아래와 같이 GET, POST, PUT, DELETE가 있으며 이 메소드는 URI와 같이 사용된다.

//리소스 조회 : 사용자 id를 통해 사용자를 조회한다.
GET /users/{id}

//리소스 생성 : 사용자를 생성한다.
POST /users

//리소스 수정 : 사용자 id를 통해 사용자 정보를 수정한다.
PUT /users/{id}

//리소스 삭제 : 사용자 id를 통해 사용자 정보를 삭제한다.
DELETE /users/{id}

 

  ③ 요청 및 응답 형식

      - API의 요청 및 응답 형식은 적절한 MIME 유형을 사용해야 하며, 일반적으로 JSON 형식이 가장 많이 사용된다.

      - 요청과 응답에서 사용되는 JSON 형식은 일관된 구조를 가지고 있어야 한다.

 

  ④ 에러처리

      - API에서 발생하는 에러 상황에 대해 HTTP 응답 코드와 에러 메시지를 사용자에게 전달한다.

      - 성공 요청에 대한 경우 200 OK 코드를, 클라이언트의 잘못된 요청에 대한 경우 400 Bad Request 코드를, 서버 측 오류가 발생한 경우 500 Internal Server Error 코드를 사용한다.

      - 또한, 응답코드 외에도 사용자가 이해할 수 있는 에러 메시지도 함께 제공하며 일반적으로 JSON 형식으로 반환한다.

{
  "error": {
    "code": 400,
    "message": "잘못된 파라미터 요청",
    "details": "~~~~~"
  }
}

 

---

Spring Boot에서 RESTful API 개발

스프링부트에서 RESTful API를 개발하기 위해서 아래의 의존성을 추가한다.

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

 

의존성 추가 후 API 엔드포인트를 작성한다.

 

스프링부트에서 제공하는 @RestController 어노테이션을 통해 컨트롤러 클래스를 작성할 수 있다.

@RequestMapping 또는 @GetMapping 어노테이션을 사용하여 엔드포인트와 HTTP 메소드를 정의한다.

 

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

    @Autowired
    private UserService userService;

    @GetMapping("/users")
    public List<User> getUsers() {
        return userService.getUsers();
    }

    @GetMapping("/users/{id}")
    public User getUserById(@PathVariable("id") Long id) {
        return userService.getUserById(id);
    }

    @PostMapping("/users")
    public User addUser(@RequestBody User user) {
        return userService.addUser(user);
    }

    @PutMapping("/users/{id}")
    public User updateUser(@PathVariable("id") Long id, @RequestBody User user) {
        return userService.updateUser(id, user);
    }

    @DeleteMapping("/users/{id}")
    public void deleteUser(@PathVariable("id") Long id) {
        userService.deleteUser(id);
    }
}

 

위 코드에서는 UserController 클래스가 @RestController 어노테이션을 이용하여 RESTful API를 구현하고 있다.

 

각각의 API는 @GetMapping, @PostMapping, @PutMapping, @DeleteMapping 어노테이션을 사용하여 HTTP 메서드에 매핑되도록 구현되어 있으며, @RequestBody 어노테이션을 이용하여 요청 본문을 객체로 변환하고, @PathVariable 어노테이션을 이용하여 URI 경로에서 파라미터를 추출할 수 있다.

 

 

에러처리

 

API에서 예외가 발생할 경우, 예외를 처리하여 적절한 에러 응답을 반환해야 한다.

이를 위해 @ExceptionHandler 어노테이션을 사용하여 예외를 처리할 수 있다.

 

@RestControllerAdvice
public class ExceptionHandlerAdvice {

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleException(Exception ex) {
        ErrorResponse errorResponse = new ErrorResponse("error", ex.getMessage());
        return new ResponseEntity<>(errorResponse, HttpStatus.BAD_REQUEST);
    }
}

 

위 코드에서는 Exception 에러가 발생하는 경우 errorResponse와 함께 400 BadRequest Http 응답코드를 함께 반환한다.

 

 

이렇게 만든 API는 API 테스트를 위한 플랫폼을 통해 테스트를 실행할 수 있다.

해당 도구는 포스트맨으로, 아래 포스팅을 참고하면 설치 및 사용방법을 익힐 수 있다.

 

2023.04.05 - [DevOps/ETC] - [Postman] API 테스트를 위한 포스트맨 설치 및 사용법

[Postman] API 테스트를 위한 포스트맨 설치 및 사용법