API의 구현과 API 명세서-1

API와 API명세서

---

API란?

API(Application Programming Interface)는 두 소프트웨어가 서로 통신할 수 있도록 하는 언어나 메시지의 형식

• 주로 서버와 클라이언트가 통신하기 위해 사용되기도 하지만, 외부 개발자에게 특정 기능을 제공하기 위해 사용되기도 한다.
• 위와 같이 공개된 API를 Open API라고 하고 여러 기업과 공공기관에서 제공하고 있다.

API명세서란?

API의 사용 방법, 요청 및 응답의 데이터 구조, 인증 방식과 같이 API와 관련된 세부적인 내용들을 설명해 놓은 문서를 의미한다.

• API에 포함되는 내용
  • 요청 정보
    • HTTP 메서드 종류 (ex, POST, GET, PUT, DELETE,,,,)
    • 엔드포인트(URL)
    • 요청에 대한 header와 body
  • 응답 정보
    • 응답의 상태 코드(ex, 2xx, 3xx, 4xx,,,,)
    • 응답에 대한 header와 body

API의 설계와 구현 (JAVA Spring framework)

서버는 Controller를 통해 요청을 처리하고 로직을 호출한다. 요청을 처리하기 위한 클래스로 @Controller 혹은 @RestController 어노테이션을 이용하여 선언한다.

• Controller 어노테이션과 ResponseEntity

  • @Controller
    • @Controller를 통해 Controller로 지정된 클래스는 주로 ViewName을 반환하며 이미 존재하는 정적 리소스(html 페이지)를 클라이언트에 전달한다.
    • 정적 리소스가 아닌 데이터만을 반환하기 위해서는 @ResponseBody 어노테이션을 추가해야 한다.
  • @RestController
    • @RestController를 통해 Controller로 지정된 클래스는 주로 JSON 타입의 데이터를 반환한다.
    • @Controller와 @ResponseBody가 합쳐진 형태이다. (따라서, @ResponseBody를 추가할 필요가 없다.)
  • ResponseEntity
    • HTTP 응답을 반환하기 위한 클래스.
    • ResponseEntity를 통해서 응답의 상태코드나 header, body 등에 대한 설정을 할 수 있다.

• Controller 사용 예시

// @Controller 사용

@Controller("/api")
public class ApiController {
        // 정적 리소스 반환
        @GetMapping("/home")
        public String home() {
                return "index.html";
        }

        // JSON데이터 반환
        @ResponseBody
        public ResponseEntity<ResponseDto> data() {
                ...  // 응답 데이터(ResponseDto) 생성하는 로직
                return ResponseEntity.status(HttpStatus.OK).body(responseDto);
        }
}

• ResponseEntity 사용 예시

// @RestController 사용

@RestController("/api")
public class ApiController {
        // JSON데이터 반환
        public ResponseEntity<ResponseDto> data() {
                ...  // 응답 데이터(ResponseDto) 생성하는 로직
                return ResponseEntity.status(HttpStatus.OK).body(responseDto);
        }
}

출처 자료- 광운대학교 멋쟁이 사자처럼 13기 백엔드 2주차