RESTful API 원칙에 대해서

들어가며

 개발을 처음 시작하며 프레임워크에 대해서 공부했을 때에는 단순히 어떻게 코드를 작성해야 데이터를 보내고 받을 수 있는 지에 대해서만 고민하기 시작했다. 점점 다양한 API를 만들어가고 다양한 사람들과 협업하면서 RESTful한 아키텍처를 지키려고 노력하게 되었다. 대부분의 레퍼런스가 모두 이 RESTful 원칙을 지켜서 API를 만든다. 그래서 별 생각 없이 은연중에 따라 RESTful을 지켜 개발하곤 한다. 오늘은 이러한 RESTful이 뭔지 자세히 정리해보려고 한다.

 

본론

API란?

먼저 API는 Application Programming Interface의 약자이다. 이 API라는 것을 통해서 어플리케이션의 데이터를 주고받을 수 있다는 것이다. 그렇게 생각하면 이 API라고 하는 것의 범위가 굉장히 넓은 표현이다. 웹소켓 통신, 웹훅 등등 다양한 방법으로 데이터를 주고받는 방법이 있기 때문이다. 하지만 우리가 일반적으로 그리고 가장 처음 접하는 API는 주로 RESTful API일 것이다. 왜냐하면 일반적으로 웹 개발에 쓰이는 API는 RESTful API를 따르기 때문이다.

 이 외에도 당연하게도 개발자들은 대부분의 API를 깔끔하게 만들고 싶어할 것이다. 그러한 과정에서 당연하게 지켜지는 것들이 있었고, 그러한 것들이 모여서 REST라는 것을 만들어냈다.

 

RESTful

RESTful은 말 그대로 REST하다는 것이다. Representational State Transfer(REST)는 API의 작동 방식이 특정한 아키텍처를 지키도록 만드는 것을 의미한다.

REST는 처음에 인터넷과 같은 복잡한 네트워크에서 통신을 관리하기 위한 지침으로 만들어졌습니다. REST 기반 아키텍처를 사용하여 대규모의 고성능 통신을 안정적으로 지원할 수 있습니다. 쉽게 구현하고 수정할 수 있어 모든 API 시스템을 파악하고 여러 플랫폼에서 사용할 수 있습니다.
API 개발자는 여러 아키텍처를 사용하여 API를 설계할 수 있습니다. REST 아키텍처 스타일을 따르는 API를 REST API라고 합니다. REST 아키텍처를 구현하는 웹 서비스를 RESTful 웹 서비스라고 합니다. RESTful API라는 용어는 일반적으로 RESTful 웹 API를 나타냅니다. 하지만 REST API와 RESTful API라는 용어는 같은 의미로 사용할 수 있습니다. - AWS

 

RESTful API가 HTTP API처럼 프로토콜이라는 이야기가 아니다. 위와 같이 REST라는 아키텍처를 따라 관습적으로 만든 API를 그냥 RESTful API라고 부른다. 우리가 유튜브 혹은 인프런에서 백엔드 API 서버를 만드는 강의를 보거나, 공식 문서에 있는 코드를 따라 API 서버를 만들게 되면, 그러한 코드들은 일반적으로 REST 아키텍처를 따른 코드들이다. 

 

그렇게 우리가 일반적으로 접하게 되는 API는 모두 RESTful API들인데, 대체 그러한 것들이 무슨 관습을 지켰길래 REST 하다는 것일까? 이제 그 아키텍처에 대해서 살펴보자.

 

1. 균일한 인터페이스

REST라는 관습에 맞춰 API 아키텍처를 설계하면 RESTful하다고 한다. 이러한 RESTful API의 특징으로는 첫번째로 균일한 인터페이스이다. 균일한 인터페이스를 맞추는 데에는 다음과 같은 조건이 있다.

• HTTP API를 사용한다.
• 서버와 클라이언트 간에 캐시가 가능해야 한다.
• 리소스에 대해서 식별가능해야한다.

이러한 조건들이 있는데, 가장 생소한 키워드은 리소스에 대해서 식별가능해야한다는 표현일 것이다. 리소스에 대해서 식별가능해야한다는 것은 URL과 HTTP 메서드를 통해서 API를 요청하는 URL만 확인하더라도 대략 어떠한 의미인 지 알 수 있게끔 구현해야 한다는 것이다. 예시를 살펴보자.

medium@MakeComputerScienceGreatAgain

위에서 API 문서인 swagger의 API 목록을 보면 깔끔하다는 것을 알 수 있다. 모두 donors로 통일되어있고 메서드만 다르다. 우리는 이러한 것을 보고 RESTful하다고 표현하는데, 이렇게 URL을 통해 리소스에 대해서 어떤 메서드를 사용할 것인지를 나타내는 것이다. 즉, 동사와 같은 것들을 url에서 제거하고, 리소스에 대해서 명시하는 것이다. 위와 같이 URL을 구성하는 것을 리소스에 대해서 식별가능하다고 표현한다.

 

2. 무상태(stateless)

무상태(stateless)는 모든 클라이언트의 요청이 다른 요청과 독립적으로 서버에서 처리된다는 것이다. 이 REST API 설계 제약 조건은 서버가 매번 요청을 완전히 이해해서 이행할 수 있음을 의미한다. 수학의 종속과 독립처럼, 모든 요청은 독립적이라는 것은 요청들이 서로 영향을 끼치지 않는다는 것이다. 이해가 조금 어렵다면 반대의 예를 들어보자.

 이러한 무상태의 반대 표현으로는 stateful이 있는데, stateful의 정의는 서버에서 클라이언트의 정보를 들고 있다는 것이다. 따라서 매번 요청에 따라 종속적으로 요청이 처리되기도 한다. 예를 들면 로그인된 사용자가 메일함을 확인했을 때의 경우가 있다. 

 

이렇게 무상태를 지켜서 API를 개발해야 예상치 못한 상황을 대비할 수 있다. API의 높은 확장성과 유연성을 목표하고 있다면 stateful하다는 것은 굉장히 위험하다는 것을 알 수 있을 것이다.

 

그렇다면 이러한 RESTful API를 사용했을 때의 이점이 무엇이 있을까?

 

확장성

REST API를 구현하는 시스템은 REST가 클라이언트와 서버간의 상호 작용을 최적화하기 때문에 효율적으로 조정할 수 있다. 또한 무상태와 서버에서의 캐싱 등을 통해서 확장성 높은 API 설계를 돕는다.

 

유연성

RESTful 웹 서비스는 완전한 클라이언트-서버 분리를 지원하는데, 이는 각 부분이 독립적으로 발전할 수 있도록 다양한 서버 구성 요소를 단순화하고 분리한다. 이러한 아키텍처는 서버 어플리케이션의 플랫폼이나 기술 변경은 클라이언트 어플리케이션에 영향을 주지 않는다.

 

독립성

RESTful API에 사용되는 기술은 무상태를 통한 독립이다. API 설계에 영향을 주지 않고 다양한 프로그래밍 언어로 클라이언트 및 서버 애플리케이션을 작성할 수 있고, 통신에 영향을 주지 않고 양쪽의 기본 기술을 변경할 수 있게 된다.

 

RESTful API를 사용하는 것에 대해 위와 같은 기술적인 장점들이 있다. 필자가 RESTful API에 대해서 관심있게 다뤄보는 이유는 기술적인 이유도 있지만, 협업할 때에도 직관적인 API의 아키텍처를 이해하는 데 큰 도움을 준다는 것이다. 이는 아래에서 다뤄보자. 

 

RESTful API의 의미

API Request의 경우

RESTful API 아키텍처는 굉장히 중요하다. 위와 같은 기술적인 이점이 있을 뿐만 아니라 협업하는 과정에서도 굉장히 큰 역할을 하게 된다. API의 개발에는 정해진 틀이 없는데, 그러한 API에 대해 어느정도 짜여진 관습을 지키면 다른 개발자와의 협업하는 과정에서도 큰 이점을 얻는다. 예를 살펴보면 다른 사람이 다음과 같은 API의 URL을 만들었다고 하자.

• /api/users/15 [GET]
• /api/users?name=marsboy [GET]
• /api/users [POST]

이러한 URL과 HTTP 메서드를 보면 이 자체만으로 어떠한 동작을 하는 지 URL 만으로 파악이 가능한 셈이다. 첫 번째의 방식은 PathVariable 방식 두 번째 방식은 PathParameter라고 부르는데, 이러한 것들을 통해서 리소스에 대한 식별을 보다 자세히 할 수 있도록 도와주는 측면이 있다.

 

첫번째 방식은 '일반적으로' userId가 15인 users에 대한 데이터를 요청하는 것으로 이해할 수 있고, 두번째 케이스는 users에 대한 데이터 중 name이라는 프로퍼티가 marsboy인 데이터를 조회하는 것으로 이해할 수 있다. 그리고 마지막 세번째 케이스는 users에 대한 값을 DB에 쓴다는 것을 알 수 있다.

 

이 외에도 URL을 작성할 때, 단수보다는 복수형을 쓴다거나 동사를 사용하지 않는다거나하는 다양한 관습이 있다. 이러한 것들은 여기서는 다루지 않도록 한다. 추가적인 레퍼런스는 마치는 부분에 유튜브 영상을 추가해두었다.

 

API Response의 경우

RESTful API는 일반적으로 HTTP 통신을 사용한다. 이러한 HTTP는 굉장히 복잡한 구조를 가지고 있으며, Response를 통해 전달받는 중요한 요소 중 하나는 상태 코드(status code)이다.

 

이러한 상태 코드 또한 관습적이다. 200번대 응답은 요청이 성공적으로 처리된 경우, 300번대는 주로 리다이렉션으로 요청이 대체된 경우, 400번대는 클라이언트에서 잘못된 요청을 보낸 경우, 500번대는 서버에서 에러가 발생한 경우의 상태 코드이다.

 

 상태 코드 또한 관습적으로 사용자에게 내려줌으로써 백엔드 개발자들끼리간이 아니라 프론트엔드 개발자와의 협업시에도 소통의 문제를 줄일 수 있다. API라는 것은 정말 무궁무진하게 만들 수 있고, 이러한 관습에 대해서 무엇이 옳은 지 아직까지 다투는 케이스도 굉장히 많다. 모든 원리원칙을 다 지켜서 API를 개발할 수는 없겠지만 적어도 어느정도 최대한 관습적으로 API를 개발하면 협업할 때 발생하는 소통에 대한 리소스를 줄일 수 있을 것이다.

 

마치며

RESTful API의 가장 큰 장점은 아무리 생각해도 협업할 때의 소통의 문제를 줄일 수 있는 것이다. URL을 통해 리소스에 대한 식별을 명확히 지켜서 개발하는 것이 협업할 때 편하게 API 개발하는 것들을 도와준다고 생각한다.

 

이러한 RESTful API라는 것에 대해서 무엇이 옳은 지 다양한 곳에서 싸움이 일어나기도 한다. 예를 들어 HTTP의 개발은 수십년이 지났지만 아직도 다음과 같은 다양한 논쟁거리가 있다.

• [야놀자] 데이터가 없을 때 200인가 404인가 : https://techblog.yogiyo.co.kr/데이터가-없을-때-200인가-404인가-f1c8c39ca9df

데이터가 없을 때 200인가 404인가?

 

유튜브에 RESTful API에 대해서 친절하게 설명해주는 영상도 있다. 관심이 있는 사람이면 찾아보면 좋을 것 같다.

• [노마드코더] 5분만에 제대로 설계하는 REST API : https://www.youtube.com/watch?v=4DxHX95Lq2U&t=178s&ab_channel=%EB%85%B8%EB%A7%88%EB%93%9C%EC%BD%94%EB%8D%94NomadCoders

 

API를 만드는 방법은 굉장히 다채롭기 때문에 다양한 고민에 빠지곤 한다. user라는 데이터를 만드는 요청을 /api/users [POST]로 놓을 것인 지, 아니면 따로 /api/signup [POST]로 두어 복잡한 인증/인가 로직을 추가할 것인 지 그때그때 깊은 고민을 하곤 한다.

 

참고

• [AWS] RESTful API란 무엇인가요? : https://aws.amazon.com/ko/what-is/restful-api/
• [Redhot] What is REST API?  : https://www.redhat.com/en/topics/api/what-is-a-rest-api

감사합니다.