RESTful한 API 설계하기

Prologue

 백엔드 서버를 개발하고 유지보수하는 개발자라면 API를 설계하고 만드는데에 많은 시간을 들이고, 어떻게 만들어야 하는지 고민을 해봤을 것이다. 나도 API를 하나 만들때마다 어떤 HTTP 함수로 만들어야 하고, URI 설계는 어떻게 해야하는지 고민을 거듭했었던 것 같다. 그렇다면 API 설계에서 중요한 개념인 REST API에 대해서 알아보고 어떻게 API를 설계하면 좀 더 RESTful한 API가 되는지 알아보도록 하자.

 

🔍 REST API란?

 REST는 Representational State Transfer의 약어로, 로이 필딩의 2000년 박사학위 논문에서 처음으로 소개된 개념이다. 로이 필딩 교수는 HTTP의 주요 저자 중 하나였으며, 당시 웹에서 통신이 사용되는 방식에 보완할 점이 많다고 생각한 후 웹의 장점을 최대한 잘 활용할 수 있는 아키텍처로써 REST를 발표했다고 한다. 개념을 간단히 표현하자면, HTTP URI를 통해서 자원을 명시하고 HTTP Method(POST, GET, PUT, DELETE)를 통해서 명시된 자원의 CRUD(Create, Read, Update, Delete)를 요청하는 API를 작성하는 것이라 할 수 있겠다.

 

📋 RESTful API의 조건

REST 아키텍처는 다음과 같은 특성을 지켜야 한다.

 

Uniform Interface (인터페이스 일관성)

인터페이스가 일관되어야 한다. URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행할 수 있어야 한다는 것이다. RESTful API라면 HTTP 표준 프로토콜을 따르는 모든 플랫폼에서 사용이 가능하다.

 

Stateless (무상태성)

API 호출한 클라이언트 상태에 대한 정보를 따로 서버에 저장하고 관리하지 않는다. 이에 따라 API 서버는 들어오는 요청에 대한 처리만 할 수 있어 서비스의 자유도가 높아지고 구현이 단순해지는 특징을 가지고 있다.

 

Cacheable (캐시 처리 가능)

HTTP라는 기존의 웹 표준을 활용하기 때문에, 캐시 기능을 사용할 수 있다. 잘 관리되는 캐싱은 클라이언트-서버 간의 상호작용을 부분적으로 또는 완전히 제거하여 성능을 향상시킬 수 있다고 한다.

 

Self-descriptiveness (자체 표현 구조)

REST API 메세지만 보고도 쉽게 이해할 수 있는 구조로 표현되어야 한다. HTTP Method 명칭이 자체 표현 구조를 따르는 예시라고 할 수 있다.

 

Client-Server 구조

Client와 Server의 역할이 확실히 구분되어야 하며, 서로간 의존성을 낮출 수 있어야 한다. 서버는 API를 제공하고 비즈니스 로직 처리 및 데이터 저장에 책임이 있으며, 클라이언트는 사용자 인증이나 상태정보를 직접 관리하는 것에 책임이 있다.

 

Layered System (계층형 구조)

REST API 서버는 다중 계층으로 구성되어 있어야 한다. RESTful API 서버는 순수 비즈니스 로직을 수행하는 API 서버와 그 앞단에 사용자 인증, 암호화, 로드 밸런싱을 하는 계층을 추가해서 구조상의 유연성을 둘 수 있다.

 

REST API URI 설계 가이드

1. 소문자를 사용하고 단어는 언더바가 아닌 하이픈으로 구분

여러 단어를 나열해야 하는 경우 카멜 표기법이 아닌 하이픈을 활용한 소문자로 URI를 만들어야 한다.

 

2. 슬래시 구분자로 계층 관계를 표현하고 마지막에는 포함시키지 않는다

정확한 계층 관계를 표현할 수 있어야 하기 때문에, 마지막에 포함시키지 않도록 하여 혼란을 주지 않아야 한다.

 

3. URI에서는 리소스에 대한 행위를 포함시키지 않는다

리소스에 대한 행위는 HTTP Method를 통해서 충분히 전달이 가능하다. 명료한 URI 작성을 위해서 리소스에 대한 행위를 포함시키지 않도록 하라.

 

4. 파일 확장자를 URI에 포함시키지 않는다

리소스 자료의 포맷을 URI 안에 포함시키지 않아야 한다. Request의 헤더에 Accept 속성을 통해서 파일의 형식을 지정해 줄 수 있다.

 

😎 Conclusion

백엔드 개발자로서 RESTful 한 코드를 작성할 수 있게 REST API의 개념에 대해 이해하고 간결한 API을 작성할 수 있도록 노력하자!