[Spring] REST API 설계 및 Controller 작성 & 설계

1. API란?

 API는 Application Programming Interface의 약자로 정의 및 프로토콜 집합을 사용하여 두 소프트웨어 구성 요소가 서로 통신할 수 있게 하는 메커니즘이다. 간단하게 말해서 요청과 응답을 사용하여서 두 애플리케이션을 서로 연결하여 통신하는 방법을 정의하는 것이 API이다. API의 역할은 아래와 같이 크게 3가지로 나누어 볼 수 있다. 

 

1) 서버와 데이터베이스에 대한 출입구 역할 

 데이터베이스에는 중요한 정보들이 저장되기 때문에 접속을 통제해야 한다. API는 이를 방지하기 위해서 서버와 데이터베이스에 대한 출입구 역할을 하며, 허용된 사람들에게만 접근성을 부여해준다. 

 

2) 프로그램끼리의 통신 가능

 API는 스마트폰 어플이나 프로그램 등의 통신 매개체 역할을 수행한다. 즉, 애플리케이션과 기기가 데이터를 원활히 주고 받을 수 있도록 돕는 역할을 한다. 

 

3) 모든 접속을 표준화 

 기계와 운영체제 등과 상관없이 누구나 동일한 액세스를 얻을 수 있도록 한다. USB-C 타입과 같이 API는 범용 플러그처럼 작동한다. 

 

2. REST 

1) 탄생

 REST는 Representational State Transfer의 약자로 프론트엔드와 백엔드가 분리되기 시작하면서 등장하였다. 2000년 로이 필딩(Roy Fielding의 박사 논문에서 처음으로 REST라는 개념이 제시되었다. 로이 필딩은 HTTP의 주요 저자 중 한 사람으로 그 당시 웹 설계의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하며 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했다. REST는 클라이언트가 서버 데이터에 액세스하는 데 사용할 수 있는 GET, PUT, DELETE 등의 함수 집합을 정의한다. 클라이언트와 서버는 HTTP를 사용하여 데이터를 교환한다. 

 

2) 구성

• 자원(Resource) - URI
  • 모든 자원에 고유한 ID가 존재하고, 이 자원은 Server에 존재한다. Client는 URI를 이용해서 자원을 지정하고 해당 자원의 상태에 대한 조작을 Server에 요청한다. 
• 행위(Verb) - HTTP METHOD
  • HTTP 프로토콜의 Method를 사용한다. HTTP 프로토콜은 GET, POST, PUT, DELETE와 같은 메서드를 제공한다. 
• 표현(Representations)
  • Client가 자원의 상태에 대한 조작을 요청하면 Server는 이에 적절한 응답을 보낸다. REST에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타내어 질 수 있다. 이 중 JSON 혹은 XML를 통해 데이터를 주고 받는 것이 일반적이다. 

 

3) 특징

 REST의 특징은 아래와 같이 6가지로 나눌 수 있다. 

• Uniform(유니폼 인터페이스)
  • Uniform Interface는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 말한다. 
• Stateless(무상태성)
  • REST API의 주된 특징은 무상태성이다. 무상태는 서버가 요청 간에 클라이언트 데이터를 저장하지 않는 것을 의미한다. 즉, 작업을 위한 상태정보를 따로 저장하고 관리하지 않는다. 세션 정보나 쿠기정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만을 단순히 처리하면 된다. 이로 인해서 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해진다. 
• Cacheable(캐시 가능)
  • HTTP라는 기존 웹표준을 그대로 사용하기 때문에 웹에서 사용하는 기존 인프라를 그대로 활용 가능하다. 따라서 HTTP가 가진 캐싱 기능도 적용할 수 있다. 
• Self-descriptiveness(자체 표현 구조)
  • REST API 메세지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조로 이루어져 있다. 
• Client-Server 구조
  • REST 서버는 API 제공, 클라이언트는 사용자 인증이나 context(세션, 로그인 정보) 등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로 간의 의존성이 줄어든다. 
• 계층형 구조
  • REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 한다. 

 

4) REST API란?

 REST API는 REST 아키텍처 스타일의 디자인 원칙을 준수하는 API이다. 최근 OpenAPI(누구나 사용할 수 있도록 공개된 API), 마이크로 서비스(하나의 큰 애플리케이션을 여러 개의 작은 애플리케이션으로 쪼개어 변경과 조합이 가능하도록 만든 아키텍처) 등을 제공하는 업체 대부분은 REST API를 제공한다. 

 

 

5) REST API 설계

 REST API 설계 시 중요한 점은 2가지로 요악할 수 있다. 첫 번째는 URI가 정보의 자원을 표현해야 한다는 것이다. 두 번째는 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다. 아래 예시를 통해서 REST API 설계 방식을 살펴보자. 

 

• 전체 사용자를 조회하는 API URI 정의
  
  • GET /users
• 특정 사용자의 인적 사항(profile) 중 이름(name)으로 조회하는 API URI 정의 
  • GET /users/profile?name=John&locale=en
  • GET /users/profile?q=name:John+locale=en
  • name으로 query parameter를 고정하게 되면 항목마다 처리하게 되므로 일반적으로 q라는 파라미터를 이용하여 그 안에 들어간 내용을 파싱하여 사용하는 형태로도 구현할 수 있다. 
• 특정 사용자의 인적 사항(profile)을 삭제하는 API URI 정의 
  • DELETE /users/{userId}/profile

 

REST API 설계 규칙  

• 모든 정보는 URI로 표현한다.
• 계층 관계를 표현할 때는 '/'를 사용한다. 
• 언더바(_)를 사용하지 않고 하이픈(-)을 사용한다.
• 띄어쓰기를 하지 않는다. 
• URI의 표현은 소문자가 적합하다. 
• URI에 확장자를 표시하지 않는다.
• URI의 표현은 동사가 아닌 명사로 한다. 
• URI 마지막에는 '/'를 붙이지 않는다. 
• 파일 확장자는 URI에 포함하지 않는다.

 

추가적으로 API 설계와 관련한 규칙들은 아래 사이트를 참고하면 좋다. 

https://www.freecodecamp.org/news/rest-api-best-practices-rest-endpoint-design-examples/

 

3. Spring Boot 

1) Spring Boot란?

 스프링 부트는 스프링의 문제점을 해결해주기 위해 개발된 스프링 프레임워크로 개발자들이 더 쉽고 빠르게 스프링 애플리케이션을 개발하도록 도와주기 위해 개발되었다. 개발 초기에 '스프링 부트 스타터'라는 프로젝트명으로 시작되었는데 이름에서도 알 수 있듯이 간단한 설정과 구성을 통해 스프링 애플리케이션의 개발을 빠르게 도와주는 프로젝트였다. 이후 프로젝트명이 '스프링 부트' 로 변경되고 2014년 4월에 공식적으로 스프링 부트 1.0이 출시되었다. 

 

2) Spring Boot 특징

• 제어 역전(Inversion of Control)
  
  • 스프링은 객체의 생명 주기 및 의존성 관리를 담당하는 IoC 컨테이너를 제공한다. 개발자는 개체의 생성과 관계 설정을 스프링에 위임할 수 있으며, 스프링 컨테이너가 객체의 생명 주기를 관리하고 필요한 의존성을 주입한다.
• 의존성 주입(Dependency Injection)
  • 스프링은 의존성 주입을 통해 객체 간의 관계를 설정한다. 의존성 주입은 애플리케이션의 결합도를 낮추고 유연성과 테스트 용이성을 향상시킨다.  
• AOP 지원(관점 지향 프로그래밍)
  • 스프링은 AOP를 지원하여 애플리케이션의 핵심 비즈니스 로직과 부가적인 기능(로깅, 트랜잭션, 관리 등)을 분리하여 모듈화할 수 있다. 
• 웹 개발 지원
  • 스프링은 웹 애플리케이션 개발을 위한 다양한 기능과 웹 프레젠테이션 계층을 제공한다. 스프링 MVC는 유연하고 확장 간으한 웹 애플리케이션을 개발할 수 있는 MVC 아키텍처를 지원한다. 

 

3) MVC

 MVC는 소프트웨어 디자인 패턴 중 하나로 애플리케이션이나 프로젝트를 구성할 때 구성요소를 세 가지 역할인 Model, View, Controller로 구분한 것이다. 

• Model
  • Data와 애플리케이션이 무엇을 할 것인지를 정의하는 부분으로 내부 비즈니스 로직을 처리하기 위한 역할을 한다. 즉, 모델은 컨트롤러가 호출을 하면 DB와 연동하여 사용자의 입출력 데이터를 다루는 일과 같은 데이터와 연관된 비즈니스 로직을 처리하는 역할을 한다. 데이터 추출, 저장, 삭제, 업데이트 등의 역할을 수행한다. 
• View
  • 사용자에게 보여주는 화면(UI)에 해당된다. 사용자와 상호작용을 하며 컨트롤러로부터 받은 모델의 결과값을 사용자에게 화면으로 출력하는 일을 한다. MVC에서는 여러 개의 VIew가 존재할 수 있다. Model에서 받은 데이터는 별도로 저장하지 않는다. 
• Controller
  • Model과 View 사이를 이어주는 인터페이스 역할을 한다. 즉, Model의 데이터를 어떻게 처리할지 알려주는 역할을 한다. 사용자로부터 View에 요청이 있다면 Controller는 해당 업무를 수행하는 Model을 호출하고 Model이 업무를 모두 수행하면 다시 결과를 View에 전달하는 역할을 한다. 

 

4) Spring Boot Component 

• Controller

package com.example.sns;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/v1")
public class TestController {
    @GetMapping("/hello")
    public ResponseEntity<String> hello(@RequestParam String name) {
        return ResponseEntity.ok("hello " + name);
    }
}

• @Service
  • Repository에서 얻어온 정보를 바탕으로 가공 후 다시 Controller에게 정보를 보내는 곳이다. Controller는 클라이언트에, Repository는 데이터에 맞닿아서 정보를 주고받는 부분으로 여길 수 있으나 실질적으로 중요한 작동이 많이 일어나는 부분이다. 애플리케이션의 비즈니스 로직 처리와 비즈니스와 관련된 도메인 모델의 적합성을 검증하고, 트랜잭션을 처리한다.

• @Repository
  • @Repository는 해당 클래스가 DB에 접근하는 클래스임을 명시한다. 스프링 데이터 접근 계층으로 인식하고 데이터 계층의 예외를 스프링 예외로 변환해준다. JPA를 사용하면 보통 JpaRepository를 상속받는다.

 

---

참고자료 

YC Tech Adacemy 강의 자료

https://aws.amazon.com/ko/what-is/api/

https://www.freecodecamp.org/news/rest-api-best-practices-rest-endpoint-design-examples/

https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html

https://inpa.tistory.com/entry/WEB-%F0%9F%8C%90-REST-API-%EC%A0%95%EB%A6%AC

https://www.elancer.co.kr/blog/view?seq=158 

https://velog.io/@cmin95/REST-API%EB%9E%80