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

💡 API 문서: API 쓰는 법을 기술해놓은 문서, 데이터를 주고 받기 위한 방법과 규격을 제공하는 문서.

📒 GitHub API 문서보기

깃헙의 API 문서

• commit 관련 API 문서 https://docs.github.com/en/rest/commits/commits

#URL sample
[GET] /repos/{owner}/{repo}/commits
https://api.github.com/repos/OWNER/REPO/commits

//나의 깃헙 commits API URL
https://api.github.com/repos/coastby/java-project2/commits

○ Path Parameter

• 주소를 통해 값을 넘길 때 사용한다.
• 주로 id 등 꼭 넣어줘야하는 파라미터

owner stringRequired : The account owner of the repository. The name is not case sensitive.

repo stringRequired : The name of the repository. The name is not case sensitive.

○ Query parameter

• ? 뒤로 전달하는 파라미터
• 선택적으로 있어도 되고 없어도 되는 파라미터

sha string : SHA or branch to start listing commits from. Default: the repository’s default branch (usually master).

path string : Only commits containing this file path will be returned.

author string : GitHub login or email address by which to filter by commit author.

since string : Only show notifications updated after the given time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

until string : Only commits before this date will be returned. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

per_page integer : The number of results per page (max 100).
Default: 30

page integer : Page number of the results to fetch.
Default: 1

○ HTTP response status codes

Status code	Description
200	OK
400	Bad Request
404	Resource not found
409	Conflict
500	Internal Error

5.2.4 @RequestParam을 이용한 GET 구현

---

• Query Parameter : GET 요청에서 ? 뒤의 쿼리스트링(query string)은 ‘{key}={value}’ 형태로 구성되어 있다.
• @RequestParam : 쿼리스트링의 키를 매개변수와 매핑하면 값을 가져올 수 있다. key값과 매개변수명이 같아야 하는데, 그럴 수 없다면 @RequestParam(”key”)로 매핑한다.
  참고) @PathVariable : URL 자체에 담긴 변수 (Path Parameter)를 받을 때 사용한다.

//변수를 통해 value를 가져올 수 있다.
@RequestParam String name

//어떤 값이 들어올 지 모르면 Map을 이용한다.
@RequestParam Map<String, String> param

[실습1] @RequestParam을 이용한 GET 구현

쿼리스트링에 어떤 값이 들어올지 모른다면 Map을 활용할 수 있다.

1. Map을 파라미터로 받는 RequestParam 작성

@GetMapping(value = "/request2")
public String getRequestParam2 (@RequestParam Map<String, String> param){
    param.entrySet().forEach((map) -> {
        System.out.printf("key : %s, value : %s", map.getKey(), map.getValue());
    });
    return "호출이 완료되었습니다.";
}

2. API tester

http://localhost:8080/api/v1/get-api/request2?name=hoon&weight=7.6

3. 결과
   a. client 화면
   

   b. console

   key : name, value : hoon
   key : weight, value : 7.6

   🚫 Error 400: 서버 내렸다가 다시 올려야 하는데 바로 함

5.2.5 DTO 객체 이용한 GET 구현

---

DAO (data access object)

• 데이터를 insert, findById, getCount, deleteAll (Create, Read, Update, Delete)

DTO (Data Transfer Object)

• 다른 레이어 간의 데이터 교환에 활용, 데이터 컨테이너 개념
• 로직이 포함되지 않는다.
• ex) User

VO (Value Object)

• 값이 있는 클래스
• DTO와 혼용하지만, 엄밀히는 다르다
• 읽기전용 (Read-Only)로 설계하며, 값을 변경할 수 없게 만들어 신뢰성을 유지한다.
• ex) Node : key와 value가 있다.

💡 VO 객체

• 커맨드 객체: HttpServletRequest를 통해 들어온 요청 파라미터들을 setter 메서드를 이용하여 객체에 정의되어있는 속성에 바인딩이 되는 객체
• 컨트롤러는 자바의 모든 자료형을 받아올 수 있음. VO 객체 또한 가능!
• VO 객체는 필드명이 중요! 클래스에 각각의 필드명이 존재하게 되는데, 필드명을 이용해서 자료를 입력받음 (객체명과 무관)
• 메서드에서 클래스나 VO가 파라미터로 들어오면 폼에서 클래스 혹은 VO가 없네~그냥 무시하자~가 아니라
• VO를 만나는 순간 어! VO 객체네? 그럼 변수명을 들여다볼까? 해서 변수명으로 매칭해줌

[실습2] DTO 객체를 활용한 GET 메서드 구현

1. 📄 MemberDto : 필드변수, constructor, getter, toString()만 구현

   • ⌨️ 코드

     public class MemberDto {
         private String name;
         private String email;
         private String organization;
     
         public MemberDto(String name, String email, String organization) {
             this.name = name;
             this.email = email;
             this.organization = organization;
         }
     
         public String getName() {
             return name;
         }
     
         public String getEmail() {
             return email;
         }
     
         public String getOrganization() {
             return organization;
         }
     
         @Override
         public String toString() {
             return "MemberDto{" +
                     "name='" + name + '\'' +
                     ", email='" + email + '\'' +
                     ", organization='" + organization + '\'' +
                     '}';
         }
     }

2. 📄 Controller : 파라미터로 DTO를 받음
   a. DTO 클래스에 선언된 필드는 컨트롤러의 메서드에서 쿼리 파라미터의 키와 매핑된다.
   b. 쿼리스트링의 키가 정해져 있지만 받아야 할 파라미터가 많을 경우 DTO 객체를 활용해 코드 가독성을 높을 수 있다.

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

3. API tester

http://localhost:8080/api/v1/get-api/request3?name=hoon&email=bob@gmai.com&organization=yeji

4. 결과 화면
   

5.3 POST API 만들기

---

⭐️ POST API

• 웹 어플리케이션을 통해 DB에 리소스를 저장할 때 사용되는 API다.
• GET API는 URL 또는 파라미터로 요청을 보내지만, POST API는 리소스나 값을 HTTP Body에 담아 전달한다.(일반적으로 JSON 형식)
• URI는 GET API에 비해 간단하다.

⭐️ 면접 질문 - GET과 Post 차이

1. 가장 큰 차이점은 HTTP 요청을 할 때 파라미터를 path나 쿼리파라미터를 쓰지 않고 Request Body에 보낸다.
2. 주로 회원가입 등 Http전송 중 노출되면 안되는 정보를 보낼 때 Post를 씁니다.

⭐️ JSON (JavaScript Object Notation)

• 자바 스크립트에서 Object (Class) 표현법
• 네트워크를 통해 데이터를 주고 받을 때 자료 형식
• JSON은 Key:Value 형식으로 자료형 Dictionary와 유사하다
  

⭐️ @RequestBody

• HTTP Body 내용을 객체에 매핑하는 역할
• Map 객체는 요청을 통해 어떤 값이 들어오게 될지 특정하기 어려울 때 주로 사용
• JSON 형식에서 데이터가 어떤 형식으로 들어올 지 모르기 때문에 Value를 Object로 처리한다.

[실습 3] @RequestBody로 POST 메서드 구현

1. ⌨️ Controller 작성

@PostMapping(value = "/member")
public String postMember(@RequestBody Map<String, Object> postData) {
    StringBuilder sb = new StringBuilder();         //Builder Pattern

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

2. API Tester
   a. URI

   http://localhost:8080/api/v1/post-api/member

   b. BODY

   {
     "name" : "hoon",
     "email" : "sleeping@gmail.com",
     "organization" : "yeji"
   }

3. 결과

   name : hoon
   email : sleeping@gmail.com
   organization : yeji

🚫 에러

2022-10-27 14:09:03.978  WARN 34200 --- [nio-8080-exec-1] .w.s.m.s.DefaultHandlerExceptionResolver : Resolved [org.springframework.http.converter.HttpMessageNotReadableException: JSON parse error: Unexpected character (''' (code 39)): was expecting double-quote to start field name; nested exception is com.fasterxml.jackson.core.JsonParseException: Unexpected character (''' (code 39)): was expecting double-quote to start field name<EOL> at [Source: (org.springframework.util.StreamUtils$NonClosingInputStream); line: 2, column: 4]]

JSON 형식이 문제였다. 따옴표로 썼는데 쌍따옴표로 써야한다.

[실습 4] DTO 객체를 활용한 POST API 구현

1. Controller

   @PostMapping(value = "/member2")
   public String postMemberDto(@RequestBody MemberDto memberDto) {
       return memberDto.toString();
   }

2. API tester

   1. URI

   http://localhost:8080/api/v1/post-api/member2

   1. BODY

   {
     "name" : "hoon",
     "email" : "sleeping@gmail.com",
     "organization" : "yeji"
   }

3. 결과 BODY

   {
     "name" : "hoon",
     "email" : "sleeping@gmail.com",
     "organization" : "yeji"
   }

5.4 PUT API 만들기

---

⭐️ PUT API

• POST와 비슷하지만 주로 Update 하는 데에 사용한다.
• POST API와 비교하면 서비스 로직에는 차이가 있지만 컨트롤러 구현은 거의 동일하다.

GET/member – select * from member between , limit 100 – list(목록)
GET/member/{id} – select * from member where id = ?
POST/member — insert RequestBody
PUT/member — update RequestBody
DELETE/member
PATCH/member — put과 비슷

💡 추가 내용
API 메서드에서 return을 객체로 하면 Content-Type이 applicatioin/json 형식으로 전달된다. (@ResponseBody)

⭐️ HttpEntity 클래스

• 스프링 프레임워크의 클래스

• Header와 Body로 구성된 HTTP 요청과 응답을 구성하는 역할을 한다.

• ResponseEntity는 서버에 들어온 요청에 대해 응답 데이터를 구성한다.

  • 이 클래스를 이용하여 응답 코드, Header, Body를 변경하고 구성할 수 있다.
  • 다른 메서드에서도 사용가능하다.
  • HttpStatus, HttpHeaders, HttpBody를 포함한다.
    
  • 💡 ResponseEntity를 사용하면, 결과값, 상태코드, 헤더값을 모두 프론트에 넘겨줄 수 있고, 에러코드도 상세하게 보낼 수 있다는 장점이 있다.
  • 사용방법

    • 생성자 이용

      return new ResponseEntity<>("success", HttpStatus.OK);
      // 단순한 메세지와 상태코드 리턴
      HttpHeaders headers = new HttpHeaders();
      headers.add("TOKEN","XXXXXX");
      return new ResponseEntity<>("Custom header set", headers, HttpStatus.OK);
      // header와 상태코드 리턴
      Message message = Messgae.builder() // Messgae 객체는 직접 만든 거.
          .message1("첫번째 메세지")
          .message2("두번째 메세지")
          .build();  
      return new ResponseEntity<>(message, HttpStatus.INTERNAL_SERVER_ERROR);
      // 메세지와 상태코드 리턴

    • static method 이용

      return ResponseEntity.ok();
      return ResponseEntity.status(HttpStatus.OK)
      				.header("Custom-Header","foo")
      				.body("Custom header set");

[실습5] ResponseEntity를 활용한 PUT 메서드 구현

1. Controller

   1. PutController 클래스 생성

   @PutMapping("/member3")
   public ResponseEntity<MemberDto> postMemberDto3(@RequestBody MemberDto memberDto){
       return ResponseEntity
               .status(HttpStatus.ACCEPTED)        //응답 코드 202
               .body(memberDto);
   } 

2. API tester
   a. URI

   http://localhost:8080/api/v1/put-api/member3

   b. BODY

   {
     "name" : "hoon",
     "email" : "sleeping@gmail.com",
     "organization" : "yeji"
   }

3. 결과

   • 이전과는 다르게 content type이 application/json으로 나온다.
     

💡 Annotation 정리

5.6 Swagger

• API 문서 자동 생성기, OAS(Open Api Specification)
• 개발자들의 필수 과제인 API 문서화를 쉽게 할 수 있도록 도와주며, 파라미터를 넣어서 실제로 어떤 응답이 오는지 테스트도 할 수 있습니다.
• 개발을 진행하는데 필수 과제인 API 문서화를 쉽게 자동화 할 수 있도록 도와주고, 페이지에서 파라미터를 넣어서 실제 응답을 테스트 할 수도 있습니다.

[실습 6] Swagger 적용하기

1. pom.xml - 안에 dependency 추가

   • ⌨️ 코드

     <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-swagger-ui</artifactId>
         <version>3.0.0</version>
     </dependency>
     <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-boot-starter</artifactId>
         <version>3.0.0</version>
     </dependency>

2. 프로젝트 아래에 configuration 패키지 생성 - SwaggerConfiguration 클래스 추가

   • ⌨️ 코드

     import org.springframework.context.annotation.Bean;
     import org.springframework.context.annotation.Configuration;
     import springfox.documentation.builders.PathSelectors;
     import springfox.documentation.builders.RequestHandlerSelectors;
     import springfox.documentation.spi.DocumentationType;
     import springfox.documentation.spring.web.plugins.Docket;
     
     @Configuration
     public class SwaggerConfiguration {
         @Bean
         public Docket api() {
             return new Docket(DocumentationType.OAS_30)
                     .select()
                     .apis(RequestHandlerSelectors.any())
                     .paths(PathSelectors.any())
                     .build();
         }
     }

   • 🚫 에러

           2022-10-27 15:20:55.045  WARN 36418 --- [           main] ConfigServletWebServerApplicationContext : Exception encountered during context initialization - cancelling refresh attempt: org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
           2022-10-27 15:20:55.064  INFO 36418 --- [           main] o.apache.catalina.core.StandardService   : Stopping service [Tomcat]
           2022-10-27 15:20:55.088  INFO 36418 --- [           main] ConditionEvaluationReportLoggingListener : 
   
           Error starting ApplicationContext. To display the conditions report re-run your application with 'debug' enabled.
           2022-10-27 15:20:55.119 ERROR 36418 --- [           main] o.s.boot.SpringApplication               : Application run failed

   1. application.properties 를 application.yml로 이름 변경
   2. application.yml에 아래와 같이 추가

   spring:
   	mvc:
   		pathmatch:
   			matching-strategy: ant_path_matcher

3. http://localhost:8080/swagger-ui/ 들어가면 아래의 화면이 나온다.

   아래에 내가 만든 API들을 볼 수 있다.