RESTful API

개발을 하다보면 한번쯤은 듣는 개념이다. 그때마다 매번 의미를 찾아보고 이해해보려하지만, 항상 잊어리는 녀석이라 이번에 제대로 정리해보려고 한다.

깊게 알아보기 전에 우선 단어로 접근해보자.

‘REST’라는 단어에 “~가득한, 아주 ~하는” 등의 의미를 나타내는 ‘ful’이라는 접미사가 붙은 형태이다.

해석하면 ‘아주 REST한 API’가 된다. 좀 더 알기 쉽게 의역하자면, REST의 원칙을 잘 따르는 API라는 의미이다.

결론적으로 REST를 이해하면 RESTful API를 이해할 수 있다.

REST

REST(Representational State Transfer)란 월드 와이드 웹(WWW)과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처의 한 형식이다.
…
엄격한 의미로 REST는 네트워크 아키텍처 원리의 모음이다.

출처: https://ko.wikipedia.org/wiki/REST

단순하게 말하자면 네트워크 아키텍처의 한 종류이다.

“Representational State Transfer”의 약자로 자원을 이름(자원의 표현)으로 구분하여 해당 자원의 상태(정보)를 주고 받는 모든 것을 의미한다.

즉, 자원의 표현에 의한 상태를 송수신하는 모든 행위들을 정의하는 것이다. 여기에서 “자원”, “표현”, “행위”는 REST를 구성하는 요소들을 의미한다.

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와 같은 Method를 제공한다.
3. 표현(Representation of Resource)
   • Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답(Representation)을 보낸다.
   • REST에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타내어 질 수 있다.
   • JSON 혹은 XML을 통해 데이터를 주고 받는 것이 일반적이다.

위 세 가지 요소로 REST를 구체적으로 정의하면 다음과 같다.

HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고, HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미한다.

JSON, XML 등의 표현으로 서버에 저장된 자원은 HTTP URI를 통해 조작할 수 있고, 해당 자원을 조작하는 행위는 HTTP Method로 정의된다는 것이다.

REST의 원칙

RESTful API를 이해하는데 구성 요소만큼 중요한 것이 원칙이다.

• Server-Client(클라이언트/서버 구조)
  • 자원이 있는 쪽이 서버, 자원을 요청하는 쪽이 클라이언트가 된다.
    • REST 서버: API를 제공하고, 비즈니스 로직 처리 및 저장을 책임진다.
    • 클라이언트: 사용자 인증이나 콘텍스트 등을 직접 관리하고 책임진다.
• Uniform Interface(인터페이스 일관성)
  • URI로 지정한 Resource에 대한 조작을 통일되고 한정적인 인터페이스로 수행한다.
  • HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.
• Stateless(무상태)
  • 각 요청 간 클라이언트의 콘텍스트가 서버에 저장되어서는 안 된다.
  • 서버는 각각의 요청을 완전히 별개의 것으로 인식하고 처리한다.
• Cacheable(캐시 처리 가능)
  • WWW에서와 같이 클라이언트는 응답을 캐싱할 수 있어야 한다.
• Layered Syste(계층화)
  • 클라이언트는 REST API 서버만 호출한다.
    • 클라이언트는 대상 서버에 직접 연결되었는지, 또는 중간 서버를 통해 연결되었는지를 알 수 없다.
  • REST 서버는 다중 계층으로 구성될 수 있다.
    • API Server는 순수 비즈니스 로직을 수행하고 그 앞단에 보안, 로드밸런싱, 암호화, 사용자 인증 등을 추가하여 구조상의 유연성을 줄 수 있다.
• Code on demaned (optional)
  • 서버로부터 스크립트를 받아서 클라이언트에서 실행한다.

REST API, RESTful API는 “자원, 표현, 행위”들이 포함되고, 해당 원칙들을 충족하는 API인 것이다.

그럼, REST는 어떤 이유로 고안 되었을까?

그 이유는 다양한 클라이언트들의 등장으로 인한 애플리케이션 분리 및 통합을 위해서 였다.

서버 프로그램은 크롬, 엣지, 사파리 등 여러 종류의 브라우저에 더해 각기 다른 아키텍쳐로 구성된 모바일 디바이스를 대응할 필요가 있어졌다.

이러한 멀티 플롯폼에 대한 대응을 위해서 클라이언트/서버 간 사이에 설계된 아키텍쳐가 필요했고, REST에 수요가 증가한 것이다.

그럼 이러한 REST를 기반으로 고안된 REST API란 어떤 것일까?

REST API

API란 뭘까?

API는 정의 및 프로토콜 집합을 사용하여 두 소프트웨어 구성 요소가 서로 통신할 수 있게 하는 메커니즘입니다.
…
Application Programming Interface의 줄임말로, API의 맥락에서 애플리케이션이라는 단어는 고유한 기능을 가진 모든 소프트웨어를 나타내며, 인터페이스는 두 애플리게이션 간의 서비스 계약이라고 할 수 있습니다. 이 계약은 요청과 응답을 사용하여 두 애플리케이션이 서로 통신하는 방법을 정의합니다.

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

REST API는 REST 기반으로 구현된 서비스 API라는 의미이며, API의 정의에 의하면 클라이언트와 서버가 REST의 원칙이 따라 서로 통신하는 방법을 정의한 것이라고 할 수 있다.

REST API 기본 설계 규칙

REST API 설계 시 가장 중요한 항목은 다음 2가지로 요약할 수 있다.

1. URI는 정보의 자원을 표현해야 한다.
2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

이것만으로는 어려우니 구체적으로 알아보자.

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

GET /members/delete/1

위와 같은 방식은 REST를 제대로 적용하지 않은 URI이다. URI는 자원을 표현하는데 중점을 두어야 하며, delete와 같은 행위에 대한 표현이 들어가서는 안된다.

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

위의 잘못된 URI를 HTTP Method를 통해 수정해 보면

DELETE /members/1

다음과 같이 된다.

회원정보를 가져올 때는 GET, 회원 추가 할 때는 POST를 사용한다.

회원 정보 조회

GET /members/show/1 (x)
GET /members/1 (o)

회원 추가

GET /members/insert/2 (x) - GET 메서드는 리소스 생성에 맞지 않는다.
POST /members/2 (o)

[참고] HTTP Method는 다음과 같은 역할을 수행한다.

Method	역할
POST	해당 URI을 요청하면 리소스를 생성한다
GET	해당 리소스를 조회한다. 리소스를 조회하고 해당 document에 대한 자세한 정보를 가져온다.
PUT	해당 리소스를 수정한다.
DELETE	해당 리소스를 삭제한다.

위와 같은 방식으로 URI은 자원, HTTP Method는 행위만을 정의하는 것이 REST API의 기본 규칙이다.

REST API 설계 규칙

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

   http://restapi.example.com/houses/apartments

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

   • URI에 포함하는 모든 글자는 리소스의 유일한 식별자로 사용되어야 한다. (URI가 다르면 리소스도 달라져야 함)
   • 혼동 방지를 위해 경로 마지막에는 슬래시(/)를 사용하지 않는다.

   http://restapi.example.com/houses/apartments/ (x)
   http://restapi.example.com/houses/apartments (o)

3. 하이픈(-)은 URI 가독성을 높이는데 사용한다.

4. 밑줄(_)은 URI에 사용하지 않는다.

5. URI 경로에는 소문자가 적합하다.

   • RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문이다.

6. 파일확장자는 URI에 포함하지 않는다.

   • REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다.
   • 대신 Accept header를 사용한다.

   http://restapi.example.com/members/soccer/345/photo.jpg (x)
   
   GET /member/soccer/345/photo HTTP/1.1 Host:restapi.example.com Accpet: image/jpg (o)

7. 리소스 간에는 연관 관계가 있는 경우

   • /리소스명/리소스ID/관계가 있는 다른 리소스명

   GET : /users/{userid}/devices # (일반적으로 소유 'has'의 관계를 표현할 때)

[참고] 응답상태코드

• 1xx: 전송 프로토콜 수준의 정보 교환
• 2xx: 클라이언트 요청이 성공적으로 수행됨
• 3xx: 클라이언트는 요청을 완료하기 위해 추가적인 행동을 취해야 함
• 4xx: 클라이언트의 잘못된 요청
• 5xx: 서버쪽 오류로 인한 상태코드

RESTful API

그럼 RESTful API란 뭘까?

‘RESTful’은 아까 처음에 정의하였듯이 ‘아주 REST한’이라는 의미이다.

REST API에 확장된 개념으로 보다 REST를 REST 답게 쓰기 위한 개념이다.

RESTful API의 목적

‘이해하기 쉽고 사용하기 쉬운 REST API를 만드는 것’

RESTful한 API를 구현하는 근본적인 목적은 성능이 아닌 이해도 및 호환성을 높이는 것이다. 따라서, 성능이 중요한 상황에서는 굳이 RESTful한 API를 구현할 필요는 없다.

RESTful 하지 못한 경우

• Ex1) CRUD 기능을 모두 POST로만 처리하는 API
• Ex2) route에 resource, id 외의 정보가 들어가는 경우(/students/updateName)

글을 마치며

정작 중요한 RESTful API는 많이 다루지 않았는데, 그것은 본질적으로 REST API와 다르지 않기 때문이다. 그럼에도 RESTful한 것이 중요한 이유는 직관적인 소통을 위함에 있다. REST는 결국 좋은 소통을 위해 고안된 개념이다. REST를 RESTful하지 못하게 사용하는 것, 즉, 어렵게 REST를 사용하는 것은 복잡하게 소통하는 것이므로 REST를 사용하지 않는 것이나 다름없다. 그렇기 때문에 RESTful을 개념자체를 알고 이해하는 것이 중요하다. RESTful API이야말로 서버에서 쉽게 데이터에 액세스할 수 있는 웹 애플리케이션을 구축하는 가장 좋은 방법이기 때문이다.

---

Reference

Wikipedia, REST, https://ko.wikipedia.org/wiki/REST
heejeong Kwon, [Network] REST란, REST API란, RESTful이란?, https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html
팬도라, Jersey를 활용한 RESTful 이해하기, https://judo0179.tistory.com/13
The Postman Team, ‘What Is a REST API? Examples, Uses, and Challenges’, https://blog.postman.com/rest-api-examples/
aws, 애플리케이션 프로그래밍 인터페이스(API)란 무엇인가요?, https://aws.amazon.com/ko/what-is/api/