REST API에 관한 간단한 고찰

yeolyeol·2023년 6월 17일

til

목록 보기

6/8

REST API를 공부하게 된 시점은 학부생 3학년 때, 모의 면접에서 CS 질문을 받은 것으로 시작되었다.
정말 매몰찬 피드백으로 인해 정신을 차리게 되었고 '이걸 모른다고?' 하는 듯한 면접관님들의 표정을 잊을 수 없었다.
하지만, 차라리 모의 면접에서 시원하게 깨지고 실제 면접에서 실마치구 않는 것이 중요하기에 마음가짐을 다시 잡고 공부했던 기억이 있다.

API (Application Programming Interface)

API

REST API를 알아보기 전, API가 무엇인지 간단하게 알고 넘어가자.

Amazon Web Services(AWS)에서 API는 아래와 같이 명시되어있다.

API는 정의 및 프로토콜 집합을 사용하여 두 소프트웨어 구성 요소가 서로 통신할 수 있게 하는 메커니즘입니다. 예를 들어, 기상청의 소프트웨어 시스템에는 일일 기상 데이터가 들어 있습니다. 휴대폰의 날씨 앱은 API를 통해 이 시스템과 ‘대화’하여 휴대폰에 매일 최신 날씨 정보를 표시합니다.

여기서, 서로 통신을 할 수 있다는 것이 API의 주요 특징이다.
API의 Full-Name에서 알 수 있듯, 고유한 기능을 가진 두 소프트웨어(어플리케이션)의 서비스 계약(인터페이스)이라고 할 수 있다.
'계약'이라고 해서 어렵게 들릴 수 있지만, 어플리케이션 끼리 Request하고 Response하며 서로 통신하는 것으로 정의한다.
그리고 API 문서에는 개발자가 이러한 Request와 Response를 구성하는 방법에 대한 정보가 들어 있다.

종류

API는 크게 4가지로 나눌 수 있다.

SOAP API
단순 객체 접근 프로토콜을 사용하는 API로, 클라이언트와 서버는 XML을 사용하여 메시지를 교환한다. 과거에 많이 사용됐지만, 유연성이 떨어진다는 단점이 있다.
RPC API
원격 프로시저(Procedure) 호출 API라고 하며, 클라이언트가 서버에서 함수나 프로시저를 완료하면 서버가 출력을 클라이언트로 다시 전송한다.
Websocket API
JSON 객체를 사용하여 데이터를 전달하는 또 다른 최신 웹 API이다. 클라이언트 앱과 서버 간의 양방향 통신을 지원하고, 서버가 연결된 클라이언트에 콜백 메시지를 전송할 수 있어 REST API보다 효율적이다. Websocket API에 대해 다음 포스팅에서 자세히 다뤄보겠다.
REST API
웹에서 가장 많이 사용되고 유연한 API이다. 클라이언트가 서버에 데이터로 요청하면 서버는 데이터를 가지고 내부 로직 함수를 실행시켜 출력 데이터를 요청한 클라이언트에게 반환(응답)한다.
~~어라? 이거 어디서 본 흐름인데?~~
REST API의 대표적인 활용을 알고 싶다면, Spring-MVC에서 확인할 수 있다.

이번 포스트에는 REST API에 대해 다뤄보겠다.

REST API

REST API의 시작

REST는 Representational State Transfer라는 용어의 약자로써 2000년도에 로이 필딩(Roy Fielding)의 박사학위 논문에서 최초로 소개되었다.
로이 필딩은 HTTP의 주요 저자 중 한사람으로서 그 당시 웹(HTTP) 설계의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하며 웹의 장점을 최대한 활요할 수 있는 아키텍처로써 REST를 발표했다.

왜 REST API 인가

프론트엔드(Front-End)와 백엔드(Back-End)가 분리되기 시작
- 새로운 서비스 개발을 위해 개발작업 진행
- JSON 형태로 데이터를 제공하는 API를 제공하자고 동의
- RequestMethod(HTTP : GET, POST, PUT, DELETE)와 URL을 이용한 정의
- View 영역이 포함되지 않은 서버사이드(Server-side) 개발을 진행
멀티플랫폼에 대한 지원을 위해 서비스 자원에 대한 아키텍처를 세우고 이용하는 방법을 모색
- 웹 + 모바일 웹
- 아이폰, 안드로이드
- etc

Configuration

REST API의 구성으로 세가지가 있다.

자원(RESOURCE) : URI
행위(Verb) : HTTP METHOD
표현(Representations)

이러한 구성이 어떻게 쓰이는지 알아보자.

Feature

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

설계

REST API를 설계할 때, 가장 중요한 것을 2가지로 요약하자면 아래와 같다.

URI는 정보의 자원을 표현해야 한다.

자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

규칙

URI는 정보의 자원을 표현해야 한다.
리소스명은 동사보다는 명사를 사용한다.

BAD CASE : GET /item/delete/1
- URI는 자원을 표현하는데 중점을 두어야 한다. delete, insert 와 같은 행위에 대한 표현이 들어가서는 안된다.

자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)로 표현
1번의 잘못된 예시로 예를 들어보자.

GOOD CASE : GET /item/delete/1 👉 DELETE /item/1
이렇게, HTTP Method로 자원에 대한 행위를 대신 표현한다.

📌 HTTP Method
HTTP Method 중 위 4가지로 CRUD가 가능하다.

⛔주의사항

URI 설계시 주의사항에 대해 알아보자.

슬래시(/) 구분자는 계층 관계를 나타내는 데 사용

# 대분류/중분류/소분류

http://localhost:8080/houses/apartments
http://localhost:8080/school/grade/class

URI 마지막 문자로 슬래시(/)를 포함하지 않는다

# URI가 다르면 리소스가 다르다는 것을 의마.
# 즉, '/'하나 차이로 리소스가 달라지기 때문에 혼동을 막기 위해 마지막에는 사용하지 않음.

http://localhost:8080/houses/apartments/ (X)
http://localhost:8080/houses/apartments  (0)

밑줄(_) 보단 하이폰(-)을 사용

# 밑줄 '_'은 문자를 가릴 수 있음.
# URI에 리소스에 대한 정보를 인식할 수 있어야함.(가독성 중요)

BAD CASE : http://localhost:8080/school/grade/class/middle_test
GOOD CASE : http://localhost:8080/school/grade/class/middle-test

URI 경로에는 소문자가 적합
RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정
파일 확장자는 URI에 포함시키지 않는다

BAD CASE : http://localhost:8080/houses/apartments/picture.png

# Accept header 사용
GOOD CASE
GET /houses/apartments/picture HTTP/1.1 Host: localhost:8080 Accept: image/jpg

리소스 간의 관계

REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 아래와 같은 표현방법으로 사용한다.

/ 리소스 명 / 리소스 ID / 관계가 있는 다른 리소스명
GET : /members/{member-id}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)
GET : /members/{member-id}/age 

# 만약, 관계가 복잡하거나 구체적인 표현이 요구될 경우
# 사용자가 구독한 채널을 조회하는 URI
GET : /members/{member-id}/subscribes/channels