API
API의 종류로는 GET, POST, PUT, DELETE 등이 있다.
사용되는 어노테이션은 다음과 같다.
@RequestController
@RequestMapping@GetMapping
@PostMapping
@PutMapping
@DeleteMapping
@RequestController, @RequestMapping 어노테이션은 공통으로 사용된다.
API 기능 테스트 도구로는 Postman을 사용해보았다.
GET API부터 직접 만들어보며, API 만드는 방법에 대해서 알아보자.
API 기능 테스트 도구로는 Postman을 사용해보았다.
GET API 만들기 (@RequestController, @RequestMapping)
GET API는 웹 애플리케이션 서버에서 값을 가져올 때 사용하는 API이다.
우선 컨트롤러에 @RestController와 @RequestMapping을 붙여 내부에 선언되는 메서드에서 사용할 공통 URL을 설정한다.
클래스 수준에서 @RequestMapping을 설정하면 내부에 선언한 메서드의 URL 리소스 앞에 @RequestMapping의 값이 공통 값으로 추가된다.
@RequestMapping 어노테이션을 별다른 설정 없이 선언하면 HTTP의 모든 요청을 받는다. 그러나 GET형식의 요청만 받기 위해서는
@GetMapping으로 설정해주면 된다.
@RestController
@RequestMapping("/api/v1/get-api")
public class GetController {
// 예제 5.26
private final Logger LOGGER = LoggerFactory.getLogger(GetController.class);
// 예제 5.2
// http://localhost:8080/api/v1/get-api/hello
@GetMapping(value = "/hello")
public String getHello() {
// 예제 5.27
LOGGER.info("getHello 메소드가 호출되었습니다.");
return "Hello World";
}
}
매개변수가 없는 GET 메서드 구현
// 예제 5.3
// http://localhost:8080/api/v1/get-api/name
@GetMapping(value = "/name")
public String getName() {
// 예제 5.27
LOGGER.info("getName 메소드가 호출되었습니다.");
return "Flature";
}
@PathVariable을 활용한 GET 메서드 구현
실무환경에서는 매개변수를 받지 않는 메서드는 거의 쓰이지 않는다. 웹 통신의 기본 목적은 데이터를 주고받는 것이기 때문에 대부분 매개변수를 받는 메서드를 작성하게 된다. 매개변수를 받을 때 자주 쓰이는 방법 중 하나는 URL 자체에 값을 담아 요청하는 것이다.
// 예제 5.4
// http://localhost:8080/api/v1/get-api/variable1/{String 값}
@GetMapping(value = "/variable1/{variable}")
public String getVariable1(@PathVariable String variable) {
// 예제 5.28
LOGGER.info("@PathVariable을 통해 들어온 값 : {}", variable);
return variable;
}
@PathVariable에 변수명을 매핑하는 방법
만약 @GetMapping 어노테이션에 지정한 변수의 이름과 메서드 매개변수의 이름을 동일하게 맞추기 어렵다면, @PathVariavle 뒤에 괄호를 열어 @GetMapping 어노테이션의 변수명을 지정해 매핑해준다.
// 예제 5.5
// http://localhost:8080/api/v1/get-api/variable2/{String 값}
@GetMapping(value = "/variable2/{variable}")
public String getVariable2(@PathVariable("variable") String var) {
return var;
}
@RequestParam을 활용한 GET 메서드 구현
GET 요청을 구현할 때, URL경로에 쿼리 형식의 값을 담아 전달하는 방법이다.
URL에서 '?'를 기준으로 우측에 '{키}={값}' 형태로 구성된 요청을 전송한다.
매개변수 부분에 @RequestParam 어노테이션을 명시해 쿼리 값과 매핑하면 된다.
// 예제 5.6, 예제 5.23
// http://localhost:8080/api/v1/get-api/request2?name=flature&email=thinkground.flature@gmail.com&organization=thinkground
@ApiOperation(value = "GET 메소드 예제", notes = "@RequestParam을 활용한 GET Method")
@GetMapping(value = "/request1")
public String getRequestParam1(
@ApiParam(value = "이름", required = true) @RequestParam String name,
@ApiParam(value = "이메일", required = true) @RequestParam String email,
@ApiParam(value = "회사", required = true) @RequestParam String organization) {
return name + " " + email + " " + organization;
}@RequestParam과 Map을 조합한 GET 메서드 구현
@RequestParam과 Map을 조합한 형태는 값에 상관없이 요청을 받을 수 있다. 예를 들어, ID같은 필수 항목이 아닌 선택항목에 대해서는 기입을 하지 않을 수도 있다. 이러한 경우에는 Map 객체로 받은 것이 효율적이다.
// 예제 5.7
// 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();
}DTO 객체를 활용한 GET 메서드 구현
DTO란?
DTO는 Data Transfer Object의 약자로, 다른 레이어 간의 데이터 교환에 활용된다. (각 클래스 및 인터페이스를 호출하면서 전달하는 매개변수로 사용되는 데이터 객체이다.)
DTO는 데이터를 교환하는 용도로만 사용하는 객체이기 때문에 DTO에는 별도의 로직이 포함되지 않는다.
DTO와 VO(Value Object)를 구분해야한다.
DTO 패키지를 따로 생성한 후 프로젝트를 진행한다.
DTO 클래스에는 전달하고자 하는 필드 객체를 선언하고 getter/setter 메서드를 구현한다. 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 객체를 활용한 GET 메서드 구현
쿼리스트링의 키가 정해져 있지만 받아야할 파라미터가 많을 경우에는 다음과 같이 DTO 객체를 활용해 코드의 가독성을 높일 수 있다.
// 예제 5.9
// http://localhost:8080/api/v1/get-api/request3?name=value1&email=value2&organization=value3
@ApiOperation(value = "GET 메소드 예제", notes = "DTO를 활용한 GET Method")
@GetMapping(value = "/request3")
public String getRequestParam3(MemberDto memberDTO) {
return memberDTO.toString();
}
POST API 만들기
POST API는 데이터베이스 등의 저장소에 리소스를 저장할 때 사용되는 API이다.
일반적으로 POST 형식의 요청은 클라이언트가 서버에 리소스를 저장하는데 사용된다.
즉, HTTP Body에 값을 넣어 전송한다. Body 영역에 작성되는 값은 일반적으로 JSON(JavaScript Object Notion) 형식으로 전송된다.
@RestController 어노테이션을 사용하고, 공통 URL을 설정하기위해 @RequestMapping 어노테이션을 사용한다.
// 예제 5.10
@RestController
@RequestMapping("/api/v1/post-api")
public class PostController {
}@RequestBody를 활용한 POST 메서드 구현
POST 형식의 요청은 클라이언트가 서버에 리소스를 저장하는데 사용한다. 즉, 리소스를 담기 위해 HTTP Body에 값을 넣어 전송한다.
Body 영역에 작성되는 값은 일반적으로 JSON 형식이다.
Map 객체는 요청을 통해 어떤 값이 들어오게 될지 특정하기 어려울 때 주로 사용한다.
@RequestBody와 Map을 활용한 POST API 구현
// 예제 5.12
// 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();
}@DTO 객체를 활용한 POST API 구현
// 예제 5.13
// http://localhost:8080/api/v1/post-api/member2
@PostMapping(value = "/member2")
public String postMemberDto(@RequestBody MemberDto memberDTO) {
return memberDTO.toString();
}PUT API 만들기
PUT API는 데이터베이스 같은 저장소에 존재하는 리소스 값을 업데이트 하는 데 사용된다.
// 예제 5.14
@RestController
@RequestMapping("/api/v1/put-api")
public class PutController {
// http://localhost:8080/api/v1/put-api/default
@PutMapping(value = "/default")
public String putMethod() {
return "Hello World!";
}
}@RequestBody를 활용한 PUT 메서드 구현
POST 메서드와 마찬가지로 값을 HTTP Body에 담아 전달한다.
- 서버에 어떤 값이 들어올지 모르는 경우에는 Map 객체를 활용한다.
- 서버에 들어오는 요청에 값이 정해져있는 경우에는 DTO 객체를 활용한다.
@RequestBody와 Map을 활용한 PUT 메서드 구현
// 예제 5.15
// http://localhost:8080/api/v1/put-api/member
@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 객체를 활용한 PUT 메서드 구현
return Dto.toString();으로 반환했을 때와return Dto로 반환했을 때의 차이를 알아야한다.
return Dto.toString();으로 반환했을 때는 문자열이 전달되고,return Dto로 반환했을 때는 JSON 형식으로 반환되었다.
// 예제 5.16
// 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;
}ResponseEntity를 활용한 PUT 메서드 구현
스프링 프레임워크에는 HttpEntity라는 클래스가 있다. HttpEntity는 Header와 Body로 구성된 HTTP 요청과 응답을 구성하는 역할을 수행한다.
이 클래스를 활용해 응답코드, Header, Body를 쉽게 구성할 수 있다.
// 예제 5.17
// 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);
}
DELETE API 만들기
DELETE API는 서버를 거쳐 데이터베이스 등의 저장소에 있는 리소스를 삭제할 때 사용한다. GET 메서드와 같이 URI에 값을 넣어 요청을 받는 형식으로 구현된다.
// 예제 5.18
@RestController
@RequestMapping("/api/v1/delete-api")
public class DeleteController {
}@PathVariable과 @RequestParam을 활용한 DELETE 메서드 구현
// 예제 5.19
// http://localhost:8080/api/v1/delete-api/{String 값}
@DeleteMapping(value = "/{variable}")
public String DeleteVariable(@PathVariable String variable) {
return variable;
}@RequestParam 어노테이션을 통해 쿼리스트링 값도 받을 수 있다.
// 예제 5.20
// http://localhost:8080/api/v1/delete-api/request1?email=value
@DeleteMapping(value = "/request1")
public String getRequestParam1(@RequestParam String email) {
return "e-mail : " + email;
}