Java/Spring

[Spring Boot] HTTP 요청을 위한 API 작성법

Dev_Green 2023. 3. 18. 14:34

0. HTTP Method

  Http 메서드란 Client와 Server 사이에서 이루어지는 요청(Request)과 응답(Response) 데이터를 전송하는 방식이다. 메서드의 종류에는 총 아홉 가지가 있으나 아래 나열한 네 가지 메서드가 주로 사용된다.

 

1. GET - 내용 취득

2. POST - 내용 저장

3. PUT - 내용 전체 갱신

4. DELETE - 내용 삭제

 

  다음으로는 Spring Boot 프로젝트에서 위 메서드들에 대한 API를 작성하는 방법이다. 먼저 메서드들이 담길 컨트롤러 클래스를 생성하고 그 컨트롤러에 @RestController를 붙여줌으로써 요청에 대한 응답값으로 JSON 형태의 데이터를 반환할 수 있도록 해준다. 그리고 필요하다면 @RequestMapping을 통해 해당 컨트롤러 내부의 메서드들에 대한 공통 URL을 설정할 수 있다.

@RestController
@RequestMapping("/test")
public class TestController {
    ...
}

 

  다음으로는 위와 같이 작성한 컨트롤러의 내부에 위치할 메서드의 작성법에 대해 알아보겠다.

1. GET API

  GET 메서드는 웹 애플리케이션 서버에서 데이터를 읽거나(Read) 검색(Retrieve)할 때 사용된다. 매개변수는 URL에 담겨 전달된다.

1. 0. GET 요청의 특징

  • 매개변수가 URL에 노출되므로 민감한 정보를 포함해서는 안된다.
  • 캐싱 가능하다.
  • 매개변수가 브라우저 기록에 남는다.
  • 전달할 수 있는 데이터의 길이에 제한이 있다. (최대 URL 길이는 2048 글자이므로)
  • 전달하는 데이터 타입은 ASCII 문자만 가능하다.

1. 1. 매개 변수가 없는 경우 

  별도의 매개변수가 없는 요청이다. 실무에서는 거의 쓰이지 않는 요청이지만 가능은 하다. 코드의 첫줄과 같은 URL로 요청을 보내면 개발자가 프로그래밍해 놓은대로 정대힌 응답을 반환한다.

// 예시: http://localhost:8080/name

@GetMapping("/name")
public String getName() {
    return "value";
}

1. 2. @PathVariable을 이용하여 매개변수를 받는 경우

  @PathVariable은 URL 자체에 값을 담아 요청하는 것이다. URL에서 중괄호({})로 표시된 곳의 위치의 값을 받아 매개변수로 삼는다. 이때, 중괄호 안의 이름과 메서드의 매개변수의 이름을 일치시켜야 한다.

// 예시: http://localhost:8080/name/Kim
    
@GetMapping("/name/{lastName}")
public String getName(@PathVariable String lastName) {
    return "Last name is" + lastName;
}

 

  중괄호 안의 이름과 매개변수의 이름을 다르게 하려면 아래와 같이 @PathVariable 어노테이션의 옵션을 설정하여 매핑할 수 있다.

@GetMapping("/name/{lastName}")
public String getName(@PathVariable("lastName") String name) {
    return "Last name is" + name;
}

1. 3. @RequestParam을 이용하여 매개변수를 받는 경우

   @RequestParam은 쿼리 형식으로 값을 전달하는 방법이다. @GetMapping에서 지정해준 URL 뒤로 '?'를 더하고 그 우측으로 '{key} = {value}' 형태로 값을 구성한다. 아래 코드와 같이 매개변수 선언 위치에서 @RequestParam 어노테이션을 명시하여 쿼리 값과 매핑하면 된다.

// 예시: http://localhost:8080/user?name=kim&age=13

@GetMapping("/user)
public String getUser(@RequestParam String name, @RequestParam String age) {
    return name + age;
}

1. 4. DTO 객체를 이용하여 매개변수를 받는 경우

  DTO를 사용하더라도 URI은 위의 @RequestParam을 이용한 경우와 같다. 하지만 메서드 선언부에서 코드의 양을 줄이고 변수들을 구조화할 수 있다.

// 예시: http://localhost:8080/name?name=kim&age=13

@GetMapping(value = "/user)
public String getUser(UserDto userDto) {
    return userDto.name + userDto.age;
}

 

2. POST API

  POST 메서드는 주로 새로운 데이터를 생성(Create)하거나 갱신(Update)할 때 사용된다. 

2. 0. POST 요청의 특징

  • GET 요청의 경우 데이터(매개변수)를 URL에 넣어 보내는 반면, POST 요청은 HTTP body에 담아 보낸다.
  • 캐싱될 수 없다.
  • 매개변수가 브라우저 기록에 남지 않는다.
  • 전달할 수 있는 데이터 길이에 제한이 없다.
  • 전달하는 데이터 타입에 제한이 없다.

2. 1. @RequestBody를 이용한 구현

   POST 요청에서는 리소스를 담기 위해 HTTP Body에 데이터를 넣어 전송한다. 이때 데이터는 일정한 형태를 취하는데 일반적으로 JSON 형식으로 전송된다. 아래와 같이 요청과 응답 각각의 Body부에 JSON 형태로 값이 담겨있는 것을 확인할 수 있다.

POST 요청 테스트

  POST API의 코드는 아래와 같이 작성할 수 있다. @RequestBody 어노테이션은 HTTP Body 내용을 해당 어노테이션이 지정된 객체와 매핑하는 역할을 한다.

  또한 ResponseEntity를 리턴타입으로 사용하면 자체적으로 HttpStatus를 설정할 수 있다.

// 예시: http://localhost:8080/company

@PostMapping("/company")
public ResponseEntity<?> saveCompany(@RequestBody RequestDto requestDto) {
    ... 

    return ResponseEntity
    	.status(HttpStatus.ACCEPTED)
        .body(requestDto);
}

3. PUT 

  PUT 메서드는 서버에 데이터를 보내어 리소스를 생성(Create)하거나 갱신(Update)할 때 사용된다. 메서드를 구성하는 방식은 POST 메서드와 마찬가지로 HTTP body를 활용한다.

3. 1. @RequestBody를 이용하여 매개변수를 받는 경우

  PUT API는 POST 메서드와 마찬가지로 값을 HTTP Body에 담아 전달한다. 

// 예시: http://localhost:8080/company

@PutMapping("/company")
public ResponseEntity<?> updateCompany(@RequestBody RequestDto request) {
    ...

    return ResponseEntity.ok(company);
}

4. DELETE

  DELETE 메서드는 웹 애플리케이션 서버를 거쳐 DB, 캐시 등의 저장소의 특정 리소스를 삭제할 때 사용된다. 이때 삭제하고자 하는 데이터를 특정하기 위한 매개변수를 받는데, GET 메서드와 같이 URI에 값을 넣어 요청을 보낸다. 마찬가지로 @PathVariable과 @RequestParam하는 방법 또한 같기 때문에 반복적인 설명은 생략하고 예시 코드만 소개하겠다.

4. 1. @PathVariable을 이용하여 매개변수를 받는 경우

// 예시: http://localhost:8080/name/Kim
    
@DeleteMapping("/name/{lastName}")
public String getName(@PathVariable String lastName) {
	...
    
    return lastName + "is deleted.";
}

4. 2. @RequestParam을 이용하여 매개변수를 받는 경우

// 예시: http://localhost:8080/user?name=kim&age=13

@DeleteMapping("/user)
public String getUser(@RequestParam String name, @RequestParam String age) {
    return name + age;
}

 

 

[참고 자료] 『스프링 부트 핵심 가이드』 장정우 지음

저작자표시