[TIL] REST API 설계 (feat. 계층형 vs 필터링 구조)

목차
1. RESTful API란?
2. REST API 디자인 가이드
3. 계층형 구조의 필요성: favorite 리소스의 역할과 관계
4. 마무리

 

개요

사이드 프로젝트에서 API의 엔드포인트를 설계하면서 많은 고민을 했다. 나는 다음과 같은 고민을 했다.

• 그럼 RESTful API란 어떤 건가?
• 지금 진행 중인 프로젝트에서는 어떻게 적용할 수 있는가?
• 고민해 봤을 때, 겹치는 엔드포인트가 있다면 어떻게 해야 하는가?

이번 글에서 RESTful API가 정확히 무엇이고 어떻게 적용할 수 있는지 기술한다. 또한, 현재 진행 중인 사이드 프로젝트에서 엔드포인트 설계과정을 서술한다. 특히, 계층형과 필터링 그리고 리소스 역할을 중점적으로 살펴본다.

 

 RESTful API란?

RESTful API란, 두 컴퓨터 시스템이 인터넷을 통해 정보를 안전하게 교환하기 위해 사용하는 인터페이스다. REST(Representational State Transfer)는 API 작동 방식에 대한 조건을 부과하는 소프트웨어 아키텍처이다. REST 아키텍처 스타일을 따르는 API를 REST API라고 한다. REST 아키텍처를 구현하는 웹 서비스를 RESTful 웹 서비스라고 한다. RESTful API라는 용어는 일반적으로 RESTful 웹 API를 나타낸다. 하지만 REST API와 RESTful API라는 용어는 같은 의미로 사용할 수 있다.

 

REST API 작동 방식

1. 클라이언트가 서버에 요청을 전송한다. 클라이언트가 API 문서에 따라 서버가 이해하는 방식으로 요청 형식을 지정한다.
2. 서버가 클라이언트를 인증하고 해당 요청을 수행할 수 있는 권한이 클라이언트에게 있는지 확인한다.
3. 서버가 요청을 수신하고 내부적으로 처리한다.
4. 서버가 클라이언트에 응답을 반환한다. 응답에는 요청이 성공했는지 여부를 클라이언트에 알려주는 정보가 포함된다. 또한, 클라이언트가 요청한 모든 정보도 포함된다.

 

REST의 특징 6가지

1. Uniform(유니폼 인터페이스) : URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 이키텍처 스타일
2. Stateless(무상태) : 작업을 위한 상태정보를 따로 저장하고 관리하지 않는다.
3. Cacheable(캐시 가능) : HTTP프로토콜 표준에서 사용하는 Last-Modified 태그나 E-Tag를 이용하면 캐싱 구현이 가능하다.
4. Self-descriptiveness(자체 표현 구조) : REST API 메시지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조로 되어있다.
5. Client-Server 구조 : 클라이언트 및 서버 애플리케이션은 서로 완전히 독립적이어야 한다. 클라이언트 애플리케이션이 알아야 하는 유일한 정보는 요청된 리소스의 URI이다.
6. 계층형 구조 : 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 프록시, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있다.

 

 REST API 디자인 가이드

REST API 중심 규칙

1. URI는 정보의 자원을 표현해야 한다. (리소스명은 동사보다는 명사를 사용)
2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)로 표현

 

URI 설계 시 주의할 점

1. 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용
2. URI 마지막 문자로 슬래시(/)를 포함 X
3. 하이픈(-)은 URI 가독성을 높이는 데 사용
4. 밑줄(_)은 URI에 사용 X
5. 소문자를 사용한다.
6. 파일 확장자는 포함 X
   • 파일 확장자는 Accept header를 사용

 

리소스 간의 관계를 표현하는 방법

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

 

자원을 표현하는 Collection과 Document

Document는 단순히 문서 또는 한 객체라고 이해하면 된다.

Collection은 문서들의 집합이라고 생각하면 된다.

컬렉션은 문서들의 집합이므로 복수로 사용한다.

 

 계층형 구조의 필요성: favorite 리소스의 역할과 관계 

적용하기에 앞서서 엔드포인트 vs URI vs URL의 차이에 대해 짚어보고 넘어가고자 한다. 해당 블로그를 작성하며 엔드포인트, URI의 단어 개념을 잘 모르니 헷갈렸다. 그런 이유에서 추가정보를 작성한다.

개념	설명	예시
Endpoint	API에서 특정 기능을 제공하는 URL의 끝점	/users/{id}
URI	리소스를 식별하는 문자열 (URN + URL 포함)	https://example.com/users/123
URL	리소스의 위치를 나타내는 문자열	https://example.com/users/123

 

변경된 엔드포인트

1. POST /api/v1/projects/{projectId}/favorite
2. POST /api/v1/resumes/{resumeId}/favorite

이전 URI는 /api/v1/favorites/projects/{projectId}로 2개의 엔드포인트가 하나로 묶여 있었다. 각 기능에 따라 2개의 엔드포인트로 나누었다. 또한, 팀원 구인글(project)을 관심목록(favorite)에 추가하는 작업이므로 favorite의 위치를 project의 뒤로 두었다.

 

왜 계층형 방식을 적용하였는가?

favorite이 자식 리소스(API에서 다루는 객체나 데이터) 역할을 하는 경우 계층 구조, 독립적인 엔티티로 다양한 관계를 관리하는 경우 필터링 방식을 사용한다.

• 독립적인 엔티티: user, product, favorite
• 종속적인 엔티티: comment (특정 post에 달려야만 의미가 있음), order_item (특정 order에 소속됨)

여기서 favorite이 다양한 관계를 (project, resume) 관리한다. 그렇다면 왜 필터링 방식을 적용하지 않는가? favorite에 연관된 관계는 더 이상 추가될 가능성이 없으며, 리소스 역할을 하기 때문이다.

 

📚 리소스의 역할을 요약하면

1. 정보 제공: 데이터나 정보를 클라이언트에게 제공.
2. 데이터 저장 및 관리: 데이터의 저장, 수정, 삭제, 상태 관리를 담당.
3. 비즈니스 로직 수행: 특정 비즈니스 규칙이나 동작을 처리.
4. 상태 관리: 리소스의 현재 상태를 추적하고 업데이트.
5. 리소스 간 관계 정의: 다른 리소스와의 관계를 정의.
6. API 추상화: API와 외부 시스템 간의 인터페이스를 제공.
7. 확장성 및 재사용성: 시스템을 확장하고 재사용할 수 있는 기반 제공.

리소스의 역할 중 4, 5번 역할을 수행한다고 볼 수 있다.

 

 마무리 

이번 글을 작성하며 RESTful API가 REST API와 같은 의미로 사용될 수 있다는 걸 알았다. 그 이전엔 REST API보다 보완된 상위 개념이 RESTful API로 알고 있었다. 또한, 엔드포인트, URI, URL 등 단어의 개념을 다시 짚고 넘어 갈 수 있었다. 이전에 궁금해서 찾아본 기억이 있지만 시간이 지나며 흐릿해져 다시 알아보았다.

엔드포인트에서 어떻게 작성해야 하는지 고민하는 시간이었다. 특히, 필터링과 계층형 구조를 대입해보며 앞으로 어떻게 적용해야 하는지 배웠다.

 

 참고자료 

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

RESTful API란 무엇인가요? - RESTful API 설명 - AWS

 

https://meetup.nhncloud.com/posts/92

REST API 제대로 알고 사용하기 : NHN Cloud Meetup