REST API를 공부하게 된 시점은 학부생 3학년 때, 모의 면접에서 CS 질문을 받은 것으로 시작되었다.
정말 매몰찬 피드백으로 인해 정신을 차리게 되었고 '이걸 모른다고?' 하는 듯한 면접관님들의 표정을 잊을 수 없었다.
하지만, 차라리 모의 면접에서 시원하게 깨지고 실제 면접에서 실마치구 않는 것이 중요하기에 마음가짐을 다시 잡고 공부했던 기억이 있다.
API (Application Programming Interface)
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
- 모든 자원에 고유한 ID가 존재하고, 이 자원은 Server에 존재한다.
- 자원을 구별하는 ID는 ‘/groups/:group_id’와 같은 HTTP URI 다.
- Client는 URI를 이용해서 자원을 지정하고 해당 자원의 상태(정보)에 대한 조작을 Server에 요청한다.
-
행위(Verb) : HTTP METHOD
- HTTP 프로토콜의 Method를 사용한다.
- HTTP 프로토콜은 GET, POST, PUT, DELETE 와 같은 메서드를 제공한다.
-
표현(Representations)
- Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답(Representation)을 보낸다.
- REST에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타내어 질 수 있다.
- JSON 혹은 XML를 통해 데이터를 주고 받는 것이 일반적이다.
특징
-
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, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있다.
장단점
장점
- HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API 사용을 위한 별도의 인프라를 구축할 필요가 없다.
- HTTP 프로토콜의 표준을 최대한 활용하여 여러 추가적인 장점을 함께 가져갈 수 있게 해준다.
- HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.
- Hypermedia API의 기본을 충실히 지키면서 범용성을 보장한다.
- REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있다.
- 여러가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다.
- 서버와 클라이언트의 역할을 명확하게 분리한다.
단점
- 표준이 존재하지 않는다.
- HTTP Method 형태가 제한적이다.
- HTTP 프로토콜에 의존한다.
- URI 설계가 복잡할 수 있다.
- 상태 정보가 클라이언트 서버 간에 전송될 수 있다.
- 필요한 문서화와 테스트 등의 추가 작업 필요하다.
설계
REST API를 설계할 때, 가장 중요한 것을 2가지로 요약하자면 아래와 같다.
- URI는 정보의 자원을 표현해야 한다.
- 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.
규칙
- URI는 정보의 자원을 표현해야 한다.
리소스명은 동사보다는 명사를 사용한다.
- BAD CASE :
GET /item/delete/1- URI는 자원을 표현하는데 중점을 두어야 한다.
delete, insert와 같은 행위에 대한 표현이 들어가서는 안된다.
- URI는 자원을 표현하는데 중점을 두어야 한다.
- 자원에 대한 행위는 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 Reference
AWS - API란 무엇입니까?
NHN Cloud Meetup! - REST API 제대로 알고 사용하기
What is an API & why does it matter for social media?
