API를 작성하는 다양한 방법

1. GET API 만들기

GET API는 웹 애플리케이션 서버에서 값을 가져올 때 사용하는 API이다. 아래 코드와 같이 컨트롤러에 @RestController와 @RequestMapping을 붙여 내부에 선언되는 메서드에서 사용할 공통 URL을 설정한다.

// 실무에서는 HTTP 메서드에 따라 컨트롤러 클래스를 구분하지 않는다.
@RestController
@RequestMapping("/api/v1/get-api")
public class GetController {
}

 

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

 

 

2. RequestMapping으로 구현하기

 

@RequestMapping은 별다른 설정 없이 선언하면 HTTP의 모든 요청을 받는다. 그러나 GET 형식의 요청만 받기 위해서는 아래 예제와 같이 어노테이션에 별도 설정이 필요하다.

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

    @RequestMapping(value = "/hello", method = RequestMethod.GET)
    public String getHello() {
        return "Hello World";
    }
}

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

• GetMapping
• @PostMapping
• @PutMapping
• @DeleteMapping

예제에서 작성한 메서드를 호출하면 Response의 Body에 'Hello World'가 반환된다.

 

 

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

 

아래 코드는 매개변수를 받을 때 자주 쓰이는 방법 중 하나로, URL 자체에 값을 담아 요청한다.

@GetMapping(value = "/variable1/{variable}")
public String getVariable1(@PathVariable String variable) {
    return variable;
}

중괄호({})로 표시하여 값을 전달한다. 값을 간단히 전달할 때 주로 사용하는 방법이며, GET 요청에서 주로 사용한다. 이러한 방식으로 코드를 작성할 때는 지켜야할 규칙이 있다. @GetMapping으로 URL을 입력할 때 중괄호를 사용해 어느 위치에서 값을 받을지 지정해야 한다. 또한 메서드의 매개변수와 그 값을 연결하기 위해 @PathVariable을 명시해야 하고, @GetMapping과 @PathVariable에 지정된 변수의 이름을 동일하게 맞춰야 한다.만약 @GetMapping에서 지정한 변수의 이름과 메서드 매개변수의 이름을 동일하게 맞출 수 없다면 아래 코드처럼 할 수 있다.

@GetMapping(value = "/variable2/{variable}")
public String getVariable2(@PathVariable("variable") String var) {
    return var;
}

@PathVariable에는 변수의 이름을 특정할 수 있는 value 요소가 존재하며, 이 위치에 변수 이름을 정의하면 매개변수와 매핑할 수 있다. 위 코드의 두 번째 줄을 풀어 쓰면 아래와 같다.

public String getVariable2(@PathVariable("value = "variable") String var) {

 

 

 

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

 

URL 경로에 값을 담아 요청을 보내는 방법 외에도 쿼리 형식으로 값을 전달할 수도 있다. 이 같은 형식을 처리하려면 @RequestParam을 이용해야 된다.

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

 

 

쿼리스트링에는 키(변수의 이름)가 모두 적혀 있기 때문에 이 값을 기준으로 메서드의 매개변수에 이름을 매핑하면 값을 가져올 수 있다. 만약 쿼리스트링에 어떤 값이 들어올지 모른다면 아래 코드와 같이 Map 객체를 활용할 수 있다.

@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();
}

 

 

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

 

DTO(Data Transfer Object)는 다른 레이어 간의 데이터 교환에 활용된다. DTO는 데이터를 교환하는 용도로만 사용하는 객체이기 때문에 DTO에는 별도의 로직이 포함되지 않는다. DTO 클래스에는 전달하고자 하는 필드 객체를 선언하고 getter/setter 메서드를 구현한다. 쿼리스트링의 키가 정해져 있지만 받아야 할 파라미터가 많을 경우에는 아래 코드와 같이 DTO 객체를 활용해 코드의 가독성을 높일 수 있다.

@GetMapping(value = "/request3")
public String getRequestParam3(MemberDto memberDto) {
    return memberDto.getName() + " " + memberDto.Email();
}

 

위처럼 DTO를 사용하면 코드의 양을 줄일 수 있다.

 

 

6. POST API 만들기

 

POST API는 웹 애플리케이션을 통해 DB 등의 저장소에 리소스를 저장할 때 사용되는 API이다. 앞서 살펴본 GET API는 URL의 경로나 파라미터에 변수를 넣어 요청을 보냈지만, POST API에서는 저장하고자 하는 리소스나 값을 HTTP Body에 담아 서버에 전달한다. 이 때문에 URI가 GET API에 비해 간단하다.

 

 

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

 

일반적으로 POST 형식의 요청은 클라이언트가 서버에 리소스를 저장하는 데 사용한다. 이 때문에 클라이언트의 요청 트래픽에 값이 포함돼 있다. 즉, POST 요청에서는 리소스를 담기 위해 HTTP Body에 값을 넣어 전송한다. (일반적으로 JSON 형식으로 전송)
JSON(JavaScript Object Notation)은 자바스크립트의 객체 문법을 따르는 문자 기반 데이터 포맷이다. 대체로 네트워크를 통해 데이터를 전달할 때 사용하며, 문자열 형태로 작성되기 때문에 파싱하기 쉽다.

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

 

 

@RequestBody는 HTTP의 Body의 내용을 해당 어노테이션이 지정된 객체에 매핑하는 역할을 한다.

Map 객체는 요청을 통해 어떤 값이 들어오게 될지 특정하기 어려울 때 주로 사용한다. 요청에 들어갈 값이 정해져 있다면 DTO 객체를 사용할 수 있다.

 

 

8. PUT API 만들기

 

PUT API는 웹 애플리케이션 서버를 통해 DB 같은 저장소에 존재하는 리소스 값을 업데이트하는 데 사용한다. POST API와 비교하면 요청을 받아 실제 DB에 반영하는 과정(서비스 로직)에 차이가 있지만, POST API와 마찬가지로 리소스를 서버에 전달하기 위해 HTTP Body를 활용해야 한다. Post와 마찬가지로 @RequestBody를 통해서 데이터를 받을 수 있다.
일반 String으로 반환하면 HEADERS의 Content-Type이 'text-plain'이지만, DTO로 반환하면 'application/json' 형식으로 자동 변환되어 전달된다.
@RestController가 지정된 클래스는 @ResponseBody를 생략할 수 있는데, 이 @ResponseBody는 자동으로 값을 
JSON과 같은 형식으로 변환해서 전달하는 역할을 수행한다.

 

 

9. DELETE APIP 만들기

 

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

 

 

참고 1. REST API 명세를 문서화하는 방법 - Swagger

 

API를 개발하면 명세를 관리해야 한다. 명세란, 핸당 API가 어떤 로직을 수행하는지 설명하고 이 로직을 수행하기 위해 어떤 값을 요청하며, 이에 따른 응답값으로는 무엇을 받을 수 있는지를 정리한 자료이다. API는 개발 과정에서 계속 변경되므로 명세 또한 계속 수정된다. 또한 이러한 명세 작업은 번거롭고 오래 걸리기 때문에 'Swagger'라는 오픈소스 프로젝트를 사용한다.

 

 

참고 2. 로깅 라이브러리 - Logback

 

로깅(logging)이란 애플리케이션이 동작하는 동안 시스템의 상태나 동작 정보를 시간순으로 기록하는 것을 의미한다. 로깅은 고객에게 필요한 기능이 아니라 디버깅이나 개발 이후 발생한 문제를 해결할 때 원인을 분석하는 데 꼭 필요한 요소이다. 자바에서는 Logback이 가장 많이 사용되는데, Logback은 log4j 이후에 출시된 로깅 프레임워크로서 slf4j를 기반으로 구현되었다. 스프링 부트의 spring-boot-starter-web 라이브러리 내부에 내장돼 있어 별도의 의존성을 추가히지 않아도 사용할 수 있다.

 

 

 

출처: 이 글의 출처는 책 '스프링 부트 핵심 가이드'를 참고하여 작성하였습니다.

https://www.yes24.com/Product/Goods/110142898