REST-API

랏 뜨·2025년 1월 2일

🔎 Overview

REST-API 개발은 여전히 백엔드 개발의 주된 방식으로 자리잡고 있다.
이는 백엔드와 프론트엔드를 명확하게 분리함으로 각 개발자들의 비용을 절감하고 퀄리티를 높이는 효과를 제공해준다.

REST-API는 무엇이며, 어떻게 동작하고 어떤 특징과 장점이 있을까?
추가로, 최근에는 REST-API의 단점을 보완한 새로운 개발 방식들도 등장하고 있다. 이러한 개발 방식들은 어떤 것들이 있을까?

📕 REST

웹에서 자원을 관리하고 접근하기 위한 아키텍처 스타일
Representational State Transfer의 약자
HTTP 프로토콜을 기반으로 클라이언트와 서버 간의 상호작용을 설계하기 위한 가이드라인 제공
주로 RESTful 웹 서비스 개발에 사용

🔒 REST의 주요 원칙

1) 자원 (Resource)

URI 를 통해 자원을 식별
ex) /post , /member/user1 ...

2) 표현 (Representation)

자원은 JSON , XML , HTML 등 다양한 형식으로 표현됨
클라이언트는 서버로부터 자원의 현재 상태를 요청하고 표현받음

3) 상태 없음 (Stateless)

서버는 클라이언트의 상태를 저장하지 않음
요청 간 클라이언트 상태를 유지하려면, 클라이언트가 모든 정보를 요청에 포함해야만 함

4) HTTP 메서드 활용

HTTP 기본 메서드를 사용하여 작업 수행
- GET : 자원 조회
- POST : 자원 생성
- PUT : 자원 전체 수정
- PATCH : 자원 일부 수정
- DELETE : 자원 삭제

5) 계층 구조 (Layered System)

클라이언트는 서버와 직접 혹은 중간 계층(프록시, 캐시 ...)을 통해 통신 가능

6) 캐시 가능 (Cacheable)

HTTP 응답은 캐시 가능해야 하며, 클라이언트는 이를 이용해 성능 최적화 가능

📕 REST-API

REST 원칙을 따르는 API
클라이언트와 서버 간 데이터를 주고받기 위해 RESTful한 방식으로 설계된 인터페이스

📂 REST-API의 구성 요소

1) 자원 (Resource)

URI 로 표현
ex) /post , /member/user ...

2) 행위 (HTTP 메서드)

HTTP 메서드를 사용해 자원에 대한 행위 정의
위에서 설명한 메서드 활용

3) 표현 (Representation)

자원의 데이터를 JSON , XML 등의 형태로 클라이언트에 전달
ex) JSON 방식은 아래와 같음

{
  "id": 1,
  "author": "작가1",
  "content": "명언1"
}

🔗 일반 웹 애플리케이션과 과 REST-API

1) 일반 웹 애플리케이션

@Controller 를 사용하여 View를 반환
HTML 파일을 반환하여 브라우저에 표시할 웹 페이지 제공
일반적으로 ModelAndView 나 String 을 반환
Thymeleaf 등 템플릿 엔진을 사용하여 HTML 을 동적으로 생성하고, 이를 클라이언트에 전달
개인 프로젝트 시 백엔드 개발과 프론트엔드 개발을 모두 진행해야 함

ex)

@Controller
@RequestMapping("/")
public class AppController {
	@GetMapping
    public String printHello(Model model) {
    	model.addAttribute("msg", "Hello!");
        return "hello";
    }
}

src/main/resources/templates/hello.html 을 미리 작성해두었다고 가정
동적 데이터 처리를 위해 Thymeleaf 를 설정해두었다고 가정
model.addAttribute() 를 사용하여, 뷰 템플릿에 동적인 데이터를 전달할 수 있게 해줌
루트 페이지를 호출하면, hello.html 뷰 페이지를 반환

2) REST-API

@RestController 를 사용하여 데이터가 표현된 형식으로 반환
- @RestController : @Controller 와 @ResponseBody 의 조합으로, 반환값을 자동으로 JSON 형식으로 변환하여 클라이언트에게 전달
일반적으로 JSON , XML 를 주로 반환하며, 다양한 형식의 데이터를 반환할 수 있음
일반 웹 애플리케이션과 달리 뷰 파일, 즉 HTML 을 반환하지 않음

ex)

@RestController
@RequestMapping("/")
public class AppController {
	@GetMapping
    public ResponseEntity<?> printHello() {
    	return ResponseEntity.ok("Hello!");
    }
}

상태코드는 HTTPStatus.OK 가 반환되고, 값으로 "Hello!" 가 넘어감
이 코드로 "Hello!"가 잘 넘어오는지 확인하는 테스트코드는 아래와 같음

@SpringBootTest
@AutoConfigureMockMvc
public class AppControllerTest {
	@Autowired
    private MockMvc mvc;
    
    @Test
    void t1() throws Exception {
        ResultActions resultActions = mvc.perform(get("/"))
                .andDo(print());

        resultActions.andExpect(handler().handlerType(AppController.class))
                .andExpect(handler().methodName("printHello"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$").value("Hello!"));
    }
}

MockMvc 를 사용하여 컨트롤러 테스트 진행
status().isOk() 로 HttpStatus.OK 가 잘 넘어오는지 확인
반환되는 값이 "Hello!" 가 맞는지 확인

⭐ REST-API의 장점

1) 프론트엔드와 백엔드의 분리

REST-API 는 프론트엔드(React, Vue, Angular 등)와 __백엔드(Spring, Django, Node.js 등)를 분리하는 데 이상적
각 개발팀이 독립적으로 작업에 집중할 수 있음

2) 클라이언트 다양성 지원

웹, 모바일 앱, 데스크톱 앱 등 다양한 클라이언트에서 동일한 API를 사용할 수 있어 재사용성이 뛰어남

3) HTTP 프로토콜 기반

HTTP 프로토콜을 사용하기 때문에 기존 웹 기술과 호환성이 좋음
Postman 등 다양한 도구로 쉽게 테스트하고 사용할 수 있음

4) 문서화 및 표준화

Swagger 등으로 API 문서를 쉽게 작성하고, 클라이언트와 명시적인 소통이 가능

📺 백엔드 프로젝트에서 REST-API를 보여주는 법

1) Postman

REST-API 테스트를 위한 도구
직접 HTTP 요청을 보내고 응답을 확인할 수 있음
이를 통해 API 동작을 시연하거나 결과를 캡처하며 REST-API 가 제대로 동작하는 것을 보여줄 수 있음

2) Swagger

REST-API 의 디자인, 문서화, 개발, 테스트 등을 위한 오픈소스 프로젝트
API 를 정의하고 테스트하며 문서화에 필요한 여러 도구 제공
프로젝트에 통합하여 API 설명서와 함께 실제로 API 를 실행하는 것도 가능
/swagger-ui.html 에서 API 실행 및 확인 가능

✔️ REST-API 외의 기술 추세

1) GraphQL

REST-API 의 단점을 보완한 데이터 쿼리 언어
Facebook에서 개발했으며, 클라이언트가 필요한 데이터만 선택해서 요청 가능
REST-API 와의 차이점
- 하나의 엔드포인트로 다양한 데이터 요청 가능
- 불필요한 데이터를 가져오거나 데이터 부족 현상이 발생하는 것을 방지