.png)
들어가며
학습 동기부여 웹 프로젝트를 진행하면서 만난 똑똑하고 멋진 팀원들덕에 RESTful API에 대해 더 깊이 알고 적용해볼 수 있었다. 설계한 API가 RESTful하다고 느끼지만 정작 RESTful 하다는 것이 무엇인지, REST가 무엇인지 물으면 정확히 설명하기는 어려울 것 같았다. 내용을 글로 정리하며 개념을 명확히 알고자 한다.
요약
RESTful API란 REST 아키텍처 원칙을 준수하여 작성된 API이며
이를 구현하는 근본적인 목적은 API의 이해도 및 호환성을 높이는 것이다.
REST란?
탄생
"Representational State Transfer(대표적인 상태 전달)"의 약자
HTTP의 주요 저자 중 한 명이던 로이 필딩이 웹의 장점을 최대한 활용할 수 있는 아키텍처로 REST를 발표(2000년도)
개념
네트워크 상에서 클라이언트와 서버 간 통신 방식 중 하나로 HTTP 프로토콜을 그대로 활용하여 만들었다.
HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고,
HTTP Method(Post, Get, Put, Delete)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미한다!
REST는 자원 기반의 구조(ROA, Resource Oriented Architecture) 설계로
중심에 Resource가 있고 HTTP Method를 통해 Resource를 처리하도록 설계된 아키텍쳐이다.
필요성
-
애플리케이션 분리 및 통합
: REST는 월드 와이드 웹(www)과 같은 분산 하이퍼미디어 시스템을 위한 아키텍처 중 하나이다. 애플리케이션이 거대해짐에 따라 모듈, 기능별로 분리와 통합이 발생하게 되는데 다른 모듈 또는 애플리케이션이라도 RESTful API를 통해 상호 통신이 가능하다. -
WEB브라우저 외의 다양한 클라이언트의 등장
다양한 브라우저와 안드로이폰, 아이폰과 같은 모바일 디바이스 등 멀티 플랫폼 시대가 도래했다. 웹 페이지를 위해 HTML 및 이미지 등을 보내던 과거의 방식이 적합하지 않은 플랫폼들이 생겨났다. RESTful API를 이용하면 데이터만 주고 받고 클라이언트에서 해당 데이터를 적절히 보여주기만 하면 된다.
REST 구성 요소
1. 자원(Resource): URI
모든 자원에 고유한 ID가 존재하고, 이 자원은 Server에 존재한다.
자원을 구별하는 ID는 '/groups/:group_id'와 같은 HTTP URI 다.
Client는 URI를 이용해서 자원을 지정하고 해당 자원의 상태(정보)에 대한 조작을 Server에 요청한다.
2. 행위(Verb): HTTP Method
HTTP 프로토콜의 Method를 사용한다.
HTTP 프로토콜은 GET, POST, PUT, DELETE, HEAD 와 같은 메서드를 제공한다.
3. 표현(Representation of Resource)
Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답(Representation)을 보낸다.
REST에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타내어 질 수 있다.
JSON 혹은 XML를 통해 데이터를 주고 받는 것이 일반적이다.
REST 특징
1) Uniform (유니폼 인터페이스)
Uniform Interface는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 말한다. HTTP 표준만 맞는다면 특정 언어나 기술에 종속받지 않고 사용 가능하다. 또한 API메시지만 보고 API가 무슨 행위를 하는 지 직관적으로 이해할 수 있음.
2) Stateless (무상태성)
REST는 작업을 위한 상태정보를 따로 저장하고 관리하지 않는다. 세션 정보나 쿠키정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만을 단순히 처리하면 됩니다. 때문에 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해진다.
3) Cacheable (캐시 가능)
REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용이 가능하다. 따라서 HTTP가 가진 캐싱 기능이 적용 가능하다. HTTP 프로토콜 표준에서 사용하는 Last-Modified태그나 E-Tag를 이용하면 캐싱 구현이 가능
4) Self-descriptiveness (자체 표현 구조)
REST API 메시지만 보고도 쉽게 이해 할 수 있는 자체 표현 구조
5) Client - Server 구조
REST 서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보)등을 직접 관리하는 구조로 각 역할이 확실히 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로간 의존성이 줄어들게 된다.
6) Layered System(계층화)
REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 한다.
REST API
설계 규칙
URI는 정보의 자원을 표현해야 한다.
동사보다는 명사를 사용한다.
소문자 복수형을 사용하여 표현한다.
Ex)GET /Member/1 -> GET /members/1
자원에 대한 행위는 HTTP Method(GET, PUT, POST, DELETE 등)로 표현한다.
URI에 HTTP Method가 들어가면 안된다.
Ex)GET /members/delete/1 -> DELETE /members/1
URI에 행위에 대한 동사 표현이 들어가면 안된다.
Ex)GET /members/show/1 -> GET /members/1
Ex)GET /members/insert/2 -> POST /members/2
그 외 규칙
- 슬래시 구분자(/ )는 계층 관계를 나타내는데 사용한다.
Ex)http://restapi.example.com/houses/apartments - URI 마지막 문자로 슬래시(/ )를 포함하지 않는다.
URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 하며 URI가 다르다는 것은 리소스가 다르다는 것이고, 역으로 리소스가 다르면 URI도 달라져야 한다.
REST API는 분명한 URI를 만들어 통신을 해야 하기 때문에 혼동을 주지 않도록 URI 경로의 마지막에는 슬래시(/)를 사용하지 않는다.
Ex)http://restapi.example.com/houses/apartments/ (X) - 하이픈(- )은 URI 가독성을 높이는데 사용
불가피하게 긴 URI경로를 사용하게 된다면 하이픈을 사용해 가독성을 높인다. - 밑줄(_ )은 URI에 사용하지 않는다.
밑줄은 보기 어렵거나 밑줄 때문에 문자가 가려지기도 하므로 가독성을 위해 밑줄은 사용하지 않는다. - URI 경로에는 소문자가 적합하다. 대문자 사용은 피하도록 한다.
RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문 - 파일확장자는 URI에 포함하지 않는다.
REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다.
Accept header를 사용한다.
Ex)http://restapi.example.com/members/soccer/345/photo.jpg (X)
Ex)GET / members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg (O) - 리소스 간에는 연관 관계가 있는 경우
/리소스명/리소스 ID/관계가 있는 다른 리소스명
Ex) GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때) - :id는 하나의 특정 resource를 나타내는 고유값
Ex)student를 생성하는 route: POST /students
Ex)id=12인 student를 삭제하는 route: DELETE /students/12
Rest API CRUD
Create : Post
Read : Get
Update : Put/Patch
Delete : Delete
예시
아래는 팀 프로젝트를 진행하며 작성했던 API의 일부분이다.
REST 구성 요소 3가지를 지켰다. 다만 전체/부분 수정을 세분화하여 PATCH 메소드까지 적용해보았는데 REST API를 다시 학습하며 보니 브라우저 호환성이 좋지 않다고 한다.
✨결론✨ RESTful의 목적
- RESTful API를 구현하는 근본적인 목적은 퍼포먼스 향상이 아닌 일관적인 컨벤션을 통한 API의 이해도 및 호환성을 높이는 것이다.
- 퍼포먼스가 중요한 상황일 때는 꼭 RESTful API로 구현할 필요는 없다.
- REST API가 유일한 정답인 것은 아니기에 무조건적으로 규칙에 매몰되기 보다 목적에 맞게 사용하면 되겠다.
참고자료
https://meetup.toast.com/posts/92
https://sanghaklee.tistory.com/57
https://velog.io/@duckchanahn/Rest-API-%EC%9D%B4%EB%A1%A0
REST 아키텍처를 훌륭하게 적용하기 위한 몇 가지 디자인 팁
