[Spring] API 작성 방법(GET API, POST API, PUT API, DELETE API)

GET API

웹 애플리케이션 서버에서 값을 가져올 때 사용하는 API
GET API를 작성하는 방법은 다양하다.

실무에서는 HTTP 메서드에 따라 컨트롤러 클래스를 구분하지 않는다고 하지만, 정확한 구분과 이해를 위해 메서드별로 클래스를 생성하였다.

GetController

컨트롤러에 @RestController, @RequestMapping을 붙여 내부에 선언되는 메서드에서 사용할 공통 URL 설정

@RestController
@RequestMapping("/api/v1/get-api")
public class GetController {
    
}

클래스 수준에서 @RequestMapping을 설정하면 내부에 선언한 메서드의 URL 리소스 앞에 @RequestMapping의 값이 공통 값으로 추가된다.

@RequestMapping으로 구현하기

@RequestMapping 어노테이션을 별다른 설정 없이 선언하면 HTTP의 모든 요청을 받는다.
GET 형식의 요청만 받기 위해서는 별도의 어노테이션 설정이 필요

@RestController
@RequestMapping("/api/v1/get-api")
public class GetController {

    // http://localhost:8080/api/v1/get-api/hello
    @RequestMapping(value = "/hello", method = RequestMethod.GET)
    public String getHello() {
        return "Hello World";
    }
}

http://localhost:8080/api/v1/get-api/hello URL을 통해 getHello() 메서드가 호출되고, 결과로 "Hello World"가 반환된다.

@RequestMapping 어노테이션의 method 요소의 값을 RequestMethod.GET으로 설정하면 요청 형식을 GET으로만 설정할 수 있다.

💡 스프링 4.3 버전 이후는 새로 나온 아래 어노테이션을 사용하기 때문에 @RequestMapping 어노테이션은 더 이상 사용되지 않는다.

• @GetMapping
• @PostMapping
• @PutMapping
• @DeleteMapping

매개변수가 없는 GET 메서드 구현

	// http://localhost:8080/api/v1/get-api/name
    @GetMapping(value = "/name")
    public String getName() {
        return "Corner";
    }

매개변수가 없는 요청은 http://localhost:8080/api/v1/get-api/name URL을 그대로 입력하고 요청할 때 스프링 부트 애플리케이션이 정해진 응답을 반환한다. getName() 메서드를 호출하고, 결과로 "Corner"가 반환된다.

@PathVariable을 활용한 GET 메서드 구현

웹 통신의 기본 목적은 데이터를 주고받는 것이기 때문에 대부분 매개변수를 받는 메서드를 작성한다. 매개변수를 받을 때 자주 쓰이는 방법 중 하나는 URL 자체에 값을 담아 요청하는 것이다.

	// http://localhost:8080/api/v1/get-api/variable1/{String 값}
    @GetMapping(value = "/variable1/{variable}")
    public String getVariable1(@PathVariable String variable) {
        return variable;
    }

이 메서드는 {중괄호}로 표시된 위치의 값을 받아 요청한다. 실제 요청 시 중괄호는 들어가지 않으며 값만 존재한다. 값을 간단히 전달할 때 주로 사용하는 방법이며, GET 요청에서 많이 사용된다.

💡 규칙

• @GetMapping 어노테이션 값으로 URL을 입력할 때 중괄호를 사용해 어느 위치에서 값을 받을지 지정
• @PathVariable 명시
• @GetMapping 어노테이션과 @PathVariable에 지정된 변수의 이름 동일

getVariable1() 메서드 호출 결과

만약 @GetMapping 어노테이션에 지정한 변수 이름과 메서드 매개변수의 이름을 동일하게 맞추기 어렵다면 @PathVariable 뒤에 괄호를 열어 @GetMapping 어노테이션의 변수명을 지정한다.

	// http://localhost:8080/api/v1/get-api/variable2/{String 값}
    @GetMapping(value = "/variable2/{variable}")
    public String getVariable2(@PathVariable("variable") String var) {
        return var;
    }

@PathVariable에는 변수의 이름을 특정할 수 있는 value 요소가 존재하며, 이 위치에 변수 이름을 정의하면 매개변수와 매핑할 수 있다 => variable과 var 매핑

@RequestParam을 활용한 GET 메서드 구현

GET 요청을 구현할 때 쿼리 형식으로 값을 전달할 수도 있다.
URI에서 '?'를 기준으로 우측에 '{키}={값}' 형태로 구성된 요청을 전송하는 방법 -> @RequestParam 어노테이션을 명시해 쿼리 값과 매핑

	// http://localhost:8080/api/v1/get-api/request1?name=value1&email=value2&organization=value3
    @GetMapping(value = "/request1")
    public String getRequestParam(@RequestParam String name, @RequestParam String email, @RequestParam String organization) {
        return name + " " + email + " " + organization;
    }

URL을 보면 '?' 오른쪽에 쿼리스트링이 명시돼 있다. 쿼리스트링에는 키(변수의 이름)가 모두 적혀 있기 때문에 이 값을 기준으로 메서드의 매개변수에 이름을 매핑하면 값을 가져올 수 있다.
키와 @RequestParam 뒤에 적는 이름을 동일하게 설정하기 어렵다면, 앞선 방법처럼 value 요소로 매핑하면 된다.

getRequestParam1() 메서드 호출 결과 => value1 value2 value3

💡 만약 쿼리스트링에 어떤 값이 들어올지 모른다면 Map 객체를 활용할 수도 있다.

	// http://localhost:8080/api/v1/get-api/request2?key1=value1&key2=value2
    @GetMapping(value = "/request2")
    public String getRequestParam2(@RequestParam Map<String, String> param) {
        StringBuilder sb = new StringBuilder();
        
        param.entrySet().forEach(map -> {
            sb.append(map.getKey() + " : " + map.getValue() + "\n");
        });
        
        return sb.toString();
    }

이처럼 코드를 작성하면 값에 상관없이 요청받을 수 있다.
예를 들어, 회원가입 관련 API에서 ID가 아닌, 취미와 같은 선택 항목에 대해서는 값을 기입하지 않는 경우에 매개변수의 항목이 일정하지 않을 수 있어 Map 객체로 받는 것이 효율적이다.

getRequestParam2() 메서드 호출 결과
key1 : value1
key2 : value2

✅ URI와 URL의 차이

• URL: 웹 주소, 리소스가 어디에 있는지 알려주기 위한 경로
• URI: 특정 리소스를 식별할 수 있는 식별자
  웹에서는 URL을 통해 리소스가 어느 서버에 위치해 있는지 알 수 있으며, 그 서버에 접근해서 리소스에 접근하기 위해서는 대부분 URI가 필요하다.

DTO 객체를 활용한 GET 메서드 구현

DTO란?

Data Transfer Object의 약자
다른 레이어 간 데이터 교환에 활용된다.
각 클래스 및 인터페이스를 호출하면서 전달하는 매개변수로 사용되는 데이터 객체

DTO는 데이터를 교환하는 용도로만 사용하는 객체이기에 별도의 로직이 포함되지 않는다.

✅ DTO와 VO의 차이
DTO와 VO(Value Object)의 역할을 서로 엄밀하게 구분하지 않고 사용할 때가 많지만 정확히 구분하자면 역할과 사용법에서 차이가 있다.

• VO: 데이터 그 자체로 의미있는 객체. 가장 특징적인 부분은 읽기전용(Read-Only)으로 설계한다는 점. 즉, VO는 값을 변경할 수 없게 만들어 데이터의 신뢰성을 유지해야 한다.
• DTO: 데이터 전송을 위해 사용되는 데이터 컨테이너. 즉, 같은 애플리케이션 내부에서 사용되는 것이 아니라 다른 서버(시스템)로 전달하는 경우에 사용된다.

DTO 클래스 예시

public class MemberDto {

    private String name;
    private String email;
    private String organization;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public String getOrganization() {
        return organization;
    }

    public void setOrganization(String organization) {
        this.organization = organization;
    }

    @Override
    public String toString() {
        return "MemberDTO{" +
                "name='" + name + '\'' +
                ", email='" + email + '\'' +
                ", organization='" + organization + '\'' +
                '}';
    }
}

DTO 클래스에는 전달하고자 하는 필드 객체 선언, getter/setter 메서드를 구현한다.
DTO 클래스에 선언된 필드는 컨트롤러의 메서드에서 쿼리 파라미터의 키와 매핑된다. 즉, 쿼리스트링의 키가 정해져 있지만 받아야 할 파라미터가 많을 경우에는 다음과 같이 DTO 객체를 활용해 코드의 가독성을 높일 수 있다.

	// http://localhost:8080/api/v1/get-api/request3?name=value1&email=value2&organization=value3
	@GetMapping(value = "/request3")
    public String getRequestParam3(MemberDto memberDto) {
        //return memberDto.getName() + " " + memberDto.getEmail() + " " + memberDto.getOrganization();
        return memberDto.toString();
    }

@getRequestParam3() 메서드 호출 결과 => MemberDTO{name='value1', email='value2', organization='value3'}

POST API

POST API는 웹 애플리케이션을 통해 데이터베이스 등의 저장소에 리소스를 저장할 때 사용되는 API이다. POST API에서는 저장하고자 하는 리소스나 값을 HTTP 바디(body)에 담아 서버에 전달한다. 그래서 URI가 GET API에 비해 간단하다.

PostController

컨트롤러 클래스에서 공통 URL 설정

@RestController
@RequestMapping("/api/v1/post-api")
public class PostController {
    
}

@RequestMapping으로 구현하기

GET API 방법과 비슷하다. 요청 처리 메서드를 정의할 때 method 요소를 RequestMethod.POST로 설정해주면 된다.

	@RequestMapping(value = "/domain", method = RequestMethod.POST)
    public String postExample() {
        return "Hello Post API";
    }

@RequestBody를 활용한 POST 메서드 구현

일반적으로 POST 형식의 요청은 클라이언트가 서버에 리소스를 저장하는 데 사용한다. 그러므로 클라이언트의 요청 트래픽에 값이 포함되어 있다. 즉, POST 요청에서는 리소스를 담기 위해 HTTP Body에 값을 넣어 전송한다.
Body 영역에 작성되는 값은 일반적으로 JSON(JavaScript Object Notation) 형식으로 전송된다.

💡 JSON이란?
JSON은 JavaScript Object Notation의 줄임말. 자바스크립트의 객체 문법을 따르는 문자 기반의 데이터 포맷이다. 현재는 자바스크립트 외에도 다수의 프로그래밍 환경에서 사용한다. 대체로 네트워크를 통해 데이터를 전달할 때 사용, 문자열 형태로 작성되기 때문에 파싱하기 쉽다.

• post 요청 작성 예시
  

	// http://localhost:8080/api/v1/post-api/member
    @PostMapping(value = "/member")
    public String postMember(@RequestBody Map<String, Object> postData) {
        StringBuilder sb = new StringBuilder();

        postData.entrySet().forEach(map -> {
            sb.append(map.getKey() + " : " + map.getValue() + "\n");
        });

        return sb.toString();
    }

@RequestMapping 대신 @PostMapping을 사용하면 method 요소를 정의하지 않아도 된다.
@RequestBody

Map 객체는 요청을 통해 어떤 값이 들어오게 될지 특정하기 어려울 때 주로 사용

• postMember() 메서드 호출 결과
  

요청 메시지에 들어갈 값이 정해져 있다면 다음과 같이 DTO 객체를 매개변수로 삼아 작성할 수도 있다.

	// http://localhost:8080/api/v1/post-api/member2
    @PostMapping(value = "/member2")
    public String postMemberDto(@RequestBody MemberDto memberDto) {
        return memberDto.toString();
    }

이처럼 작성하면 MemberDto의 멤버 변수를 요청 메시지의 키와 매핑해 값을 가져온다.

PUT PAI

PUT API는 웹 애플리케이션 서버를 통해 데이터베이스 같은 저장소에 존재하는 리소스 값을 업데이트하는 데 사용한다. POST API와 비교하면 요청을 받아 실제 데이터베이스에 반영하는 과정(서비스 로직)에서 차이가 있지만, 리소스를 서버에 전달하기 위해 HTTP Body를 활용하기 때문에 컨트롤러 클래스를 구현하는 방법은 POST API와 거의 동일하다.

PutController

@RestController
@RequestMapping("/api/v1/put-api")
public class PutController {
    
}

@RequestBody를 활용한 PUT 메서드 구현

PUT API는 POST 메서드와 마찬가지로 값을 HTTP Body에 담아 전달한다. 서버에서는 이 값을 받기 위해 @RequestBody를 사용한다.

• 서버에 어떤 값이 들어올지 모르는 경우 Map 객체를 활용해 값을 받음

	@PutMapping(value = "/member")
    public String postMember(@RequestBody Map<String, Object> putData) {
        StringBuilder sb = new StringBuilder();
        
        putData.entrySet().forEach(map -> {
            sb.append(map.getKey() + " : " + map.getValue() + "\n");
        });
        
        return sb.toString();
    }

• 서버에 들어오는 요청에 담겨 있는 값이 정해져 있는 경우, DTO 객체를 활용해 구현

	// http://localhost:8080/api/v1/put-api/member1
    @PutMapping(value = "/member1")
    public String postMemberDto1(@RequestBody MemberDto memberDto) {
        return memberDto.toString();
    }

    // http://localhost:8080/api/v1/put-api/member2
    @PutMapping(value = "/member2")
    public MemberDto postMemberDto2(@RequestBody MemberDto memberDto) {
        return memberDto;
    }

postMemberDto1 메서드는 리턴 값이 String 타입이고, postMemberDto2 메서드는 리턴 값이 DTO 객체 타입이다.

다음 사진과 같이 첫 번째 메서드를 테스트하기 위해 PUT 요청을 보내면,


이와 같이 String 타입으로 값을 전달받게 되며, 리턴 값으로 설정한 DTO 객체의 toString 메서드 결과값이 출력된다.

HEADERS 항목의 Content-Type을 보면 'text/plain'으로서 결과값으로 일반 문자열이 전달됐음을 확인할 수 있다.

이번에는 두 번째 메서드를 테스트하기 위해 PUT 요청을 보내면,


다음과 같은 결과값이 나온다. 우측의 BODY 값은 실제로 형식만 유지한 채 전달된다. HEADERS 영역의 Content-Type 항목을 보면 'application/json' 형식으로 전달된 것을 확인할 수 있다.
@RestController 어노테이션이 지정된 클래스는 @RequestBody를 생략할 수 있는데, 이 @RequestBody 어노테이션은 자동으로 값을 JSON과 같은 형식으로 변환해서 전달하는 역할을 수행한다.

ResponseEntity를 활용한 PUT 메서드 구현

스프링 프레임워크에는 HttpEntity라는 클래스가 있다. HttpEntity는 다음과 같이 헤더(Header)와 Body로 구성된 HTTP 요청과 응답을 구성하는 역할을 수행한다.

HttpEntity 클래스

public class HttpEntity<T> {
	
    private final HttpHeaders headers;
    
    @Nullable
    private final T body;
    
    ...
}

RequestEntity와 ResponseEntity는 HttpEntity를 상속받아 구현한 클래스.

• ResponseEntity - 서버에 들어온 요청에 대해 응답 데이터를 구성해 전달
• ResponseEntity - HttpEntity로부터 HttpHeaders와 Body를 가지고 자체적으로 HttpStatus 구현

ResponseEntity 클래스

public class ResponseEntity<T> extends HttpEntity<T> {

	private final Object status;
    
    ..생략..
}

이 클래스를 활용하면 응답 코드 변경은 물론 Headers와 Body를 더욱 쉽게 구성할 수 있으며, PUT 메서드 외에 다른 메서드에서도 모두 사용할 수 있는 클래스이다.

	// http://localhost:8080/api/v1/put-api/member3
    @PutMapping(value = "/member3")
    public ResponseEntity<MemberDto> postMemberDto3(@RequestBody MemberDto memberDto) {
        return ResponseEntity.status(HttpStatus.ACCEPTED).body(memberDto);
    }

postMemberDto3 메서드의 리턴 타입을 ResponseEntity로 설정하고 리턴 값을 만든다. status에 넣을 수 있는 값은 다양한데, HttpStatus.ACCEPTED는 응답 코드 202를 가지고 있다. 즉, 이 메서드를 대상으로 요청을 수행하면 다음과 같이 응답 코드가 202로 변경된다.

DELETE API

DELETE API는 웹 애플리케이션 서버를 거쳐 데이터베이스 등의 저장소에 있는 리소스를 삭제할 때 사용한다. 서버에서는 클라이언트로부터 리소스를 식별할 수 있는 값을 받아 데이터베이스나 캐시에 있는 리소스를 조회하고 삭제하는 역할을 수행한다. 이때 컨트롤러를 통해 값을 받는 단계에서는 간단한 값을 받기 때문에 GET 메서드와 같이 URI에 값을 넣어 요청을 받는 형식으로 구현된다.

DeleteController

@RestController
@RequestMapping("/api/v1/delete-api")
public class DeleteController {
    
}

@PathVariable과 @RequestParam을 활용한 DELETE 메서드 구현

@PathVariable을 이용하면 다음과 같이 URI에 포함된 값을 받아 로직 처리 가능

	// http://localhost:8080/api/v1/delete-api/{String값}
    @DeleteMapping(value = "/{variable}")
    public String DeleteVariable(@PathVariable String variable) {
        return variable;
    }

@DeleteMapping 어노테이션에 정의한 value의 이름과 메서드의 매개변수 이름을 동일하게 설정해야 삭제할 값이 주입된다.

또는 다음과 같이 @RequestParam 어노테이션을 통해 쿼리스트링 값을 받을 수도 있다.

	// http://localhost:8080/api/v1/delete-api/request1?email=value
    @DeleteMapping(value = "/request1")
    public String getRequestParam1(@RequestParam String email) {
        return "e-mail : " + email;
    }

[출처] 책 스프링 부트 핵심 가이드 (장정우), 위키북스