Chapter 05. API를 작성하는 다양한 방법

이 글은 스프링 부트 핵심 가이드(장정우 저)를 읽고 개인적으로 정리하기 위한 글입니다.

GET API

• 웹 애플리케이션 서버에서 값을 가져올 때 사용하는 API
• @RequestMapping : HTTP의 모든 요청을 받는 어노테이션
• 스프링 4.3 버전 이후로는 새로 나온 어노테이션(@GetMapping, @DeleteMapping, @PostMapping, @PutMapping)을 사용하기 때문에 @RequestMapping은 잘 사용되지 않음

컨트롤러 클래스에 @RestController와 @RequestMapping 설정

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

 

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

• 실무 환경에서는 매개변수를 받지 않는 메서드가 거의 쓰이지 않음
• 매개변수를 받을 때 자주 쓰이는 방법 중 하나 URL 자체에 값을 담아 요청하는 것

// http://localhost:8080/api/v1/get-api-variable1/{String 값}
@GetMapping(value = "/variable1/{variable}")
public String getVariable1(@PathVariable String variable) {
	return variable; // url에 넣은 입력값이 출력이 된다.
}

// @PathVariable에 변수명을 매핑하는 방법
@GetMapping(value = "/variable1/{variable}")
public String getVariable1(@PathVariable("variable") String var) {
	return var; // url에 넣은 입력값이 출력이 된다.
}

 

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

• URL 경로에 값을 담아 요청을 보내는 방법 외에도 쿼리 형식으로 값을 전달할 수도 있다.
• URI에서 ?를 기준으로 우측에'{Key}={Value}' 형태로 구성된 요청을 전송하는 방법
• 쿼리스트링에 어떤 값이 들어올지 모른다면 Map 객체를 활용할 수도 있다.

// http://localhost:8080/api/v1/get-api-request1?name=kim&email=test@naver.com
@GetMapping("/request1")
public String getRequestParam(
	@RequestParam String name,
    	@RequestParam String email) {
    
	return name + " " + email // kim test@naver.com;
}

//  http://localhost:8080/api/v1/get-api-request1?key1=value1&key2=value2
@GetMapping("/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();
}

URI와 URL 차이
URL은 우리가 흔히 말하는 웹 주소를 의미하며, 리소스가 어디에 있는지 알려주기 위한 경로를 의미,

반면 URI는 특성 리소스를 식별할 수 있는 식별자를 의미 웹에서는 URL을 통해 리소스가 어느 서버에 위치해 있는지 알 수 있으며, 그 서버에 접근해서 리소스에 접근하기 위해서는 대부분 URI가 필요

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

DTO?

• Data Transfer Object, 다른 레이어 간의 데이터 교환에 활용, 각 클래스 및 인터페이스를 호출하면서 전달하는 매개변수로 사용되는 데이터 객체
• DTO는 데이터를 교환하는 용도로만 사용되는 객체이기 때문에 DTD에는 별도의 로직이 포함되지 않음

// 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;
    }
}

 

POST API

• 웹 에플리케이션을 통해 데이터베이스 등의 저장소에 리소스를 저장할 때 사용되는 API
• GET API에서는 URL의 경로나 파라미터에 변수를 넣어 요청을 보냄
• POST API에서는 저장하고자 하는 리소스나 값을 HTTP 바디(body)에 담아 서버에 전달
• 그래서 URI가 GET API에 비해 간단

@RequestMapping으로 구현하기

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

// 위와 결과는 같다 RequestMapping보다는 PostMapping 사용!!!
@PostMapping("/domain)
public String postExample2() {
	return "Hello Post API";
}

 

RequestBody를 활용한 Post 메서드 구현

• POST 요청에서는 리소스를 담기 위해 HTTP Body에 값을 넣어 전송
• Body영역에 작성되는 값은 일정한 형태를 취한다.
• 일반적으로 JSON 형식으로 전송

// http://localhost:8080/api/v1/post-api/member
// @RequestBody와 Map을 활용한 POST API 구현
@PostMapping("/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();
}

// DTO 객체를 활용한 POST API 구현
// http://localhost:8080/api/v1/post-api/member2
@PostMapping("/member2)
public String postMemberDto(@RequestBody MemberDto memberDto) {
	return memberDto.toString();
}

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

 

PUT API

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

@RequestBody를 통한 PUT 메서드 구현

// http://localhost:8080/api/v1/put-api/member
@PutMapping("/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();
}

// http://localhost:8080/api/v1/put-api/member2
@PutMapping("/member2")
public MemberDto postMemberDt o2(@ReqeustBody MemberDto memberDto) {
	return memberDto; // 응답으로 memberDto 객체를 JSON 형식으로 반환
}

DELETE API

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

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

// @PathVariable을 활용한 DELETE 메서드 구현
// http://localhost:8080/api/v1/delete-api/{String 값}
@DeleteMapping(value = "/{variable}"}
public String deleteVariable(@PathVariable String variable) {
	return variable;
}

// @RequestParam을 활용한 DELETE 메서드 구현
// http://localhost:8080/api/v1/delete-api/request1?email=value
@DeleteMapping("/request1)
public String getReuqestParam1(@RequestParam String email) {
	return "email: " + email;
}

REST API 명세를 문서화 하는 방법

Swagger

• 명세 : 해당 API가 어떤 로직을 수행하는지 설명하고 이 로직을 수행하기 위해 어떤 값을 요청하며, 이에 따른 응답값으로는 무엇을 받을 수 있는지를 정리한 자료

Swagger 의존성 추가

swagger 의존성 추가

Swagger 설정 코드

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
	
    @Bean
    public Docket api() {
    	return new Docket(DocumentationType.SWAGGER_2)
        	.apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.springboot.api"))
            .paths(PathSelectors.any())
            .build();
    }
    
    private ApiInfo apiInfo() {
    	return new ApiInfoBuilder()
        	.title("Spring Boot Open API Test with Swagger")
            .description("설명 부분")
            .version("1.0.0")
            .build();
            
    }
}

// 기존 코드에 Swagger 명세를 추가
@ApiOperation(value = "GET 메서드 예제", notes = "@RequestParam을 활용한 GET Method")
@GetMapping("/request1")
public String getRequestParam(
	@ApiParam(value = "이름", required = true) @RequestParam String name,
    	@ApiParam(value = "이메일", required = true)@RequestParam String email) {
    
	return name + " " + email // kim test@naver.com;
}

• @ApiOperation : 대상 API의 설명을 작성하기 위한 어노테이션
• @ApiParam : 매개변수에 대한 설명 및 설정을 위한 어노테이션, 메서드의 매개변수 뿐 아니라 DTO 객체를 매개변수로 사용할 경우 DTO 클래스 내의 매개변수에도 정의할 수 있음

로깅 라이브러리

로깅?
애플리케이션이 동작하는 동안 시스템의 상태나 동작 정보를 시간순으로 기록하는 것을 의미
로깅은 개발 영역 중 ‘비기능 요구사항’, 즉 사용자가나 고객에게 필요한 기능은 아니다
하지만 디버깅하거나 개발 이후 발생한 문제를 해결할 때 원인을 분석하는데 꼭 필요한 요소

Logback

• 자바 진영에서 가장 많이 사용되는 로깅 프레임워크는 LogBack
• log4j 이후에 출시된 로깅 프레임워크, slf4j를 기반으로 구현
• 과거에 사용되던 log4j에 비해 월등한 성능을 자랑

Logback의 특징

• 크게 5개의 로그 레벨(TRACE, DEBUG, INFO, WARN, ERROR)를 설정할 수 있다.
  • ERROR : 로직 수행 중에 시스템에 심각한 문제가 발생해서 애플리케이션의 작동이 불가능한 경우
  • WARN : 시스템 에러의 원인이 될 수 있는 경고 레벨을 의미
  • INFO : 애플리케이션의 상태 변경과 같은 정보 전달을 위해 사용
  • DEBUG : 애플리케이션의 디버깅을 위한 메세지를 표시하는 레벨을 의미
  • TRACE : DEBUG 레벨보다더 상세한 메세지를 표현하기 위한 레벨을 의미
• 실제 운영 환경과 개발 환경에서 각각 다른 출력 레벨을 설정해서 로그를 확인 가능
• Logback의 설정 파일을 일정시간마다 스캔해서 애플리케이션을 재가동하지 않아도 설정을 변경 가능
• 별도의 프로그램 지원 없이도 자체적으로 로그 파일을 압축할 수 있음
• 저장된 로그 파일에 대한 보관 기간 등을 설정해서 관리할 수 있음