API를 RESTful하게 수정해보자

24 Jun 2024

회사에서 레거시 API를 RESTful하게 전환하는 과정을 정리해보자.

REST API?, RESTful?

먼저 REST, REST API, RESTful 용어를 정리해보자.

REST(Representational State Transfer)

REST는 웹 서비스 아키텍처 스타일의 하나로, 시스템 간의 상호작용을 간단하고 효율적으로 만들기 위한 원칙을 정의한다.

REST는 웹에서 자원을 처리하는 방식으로 네트워크 상의 시스템들이 상호작용하는 방법에 대한 규칙을 제공한다.

REST는 약자로 자원을 이름으로 구분하여 자원의 상태를 주고받는 모든 것을 의미하는 것이다.

REST는 3가지의 구성 요소를 가지고 있다.

• 자원: HTTP URI를 통해 자원을 명시
• 자원에 대한 행위: HTTP Method를 이용(GET, POST 등)
• 자원에 대한 행위의 내용: URI에 대한 CRUD를 적용하는 것을 의미

REST API

REST API는 REST 아키텍처 스타일을 따르는 웹 서비스 인터페이스이다.

REST API는 클라이언트가 서버와 데이터를 교환할 때 REST의 규칙을 따른다.

즉, 자원을 HTTP 메서드로 처리하는 API다.

RESTful

RESTful은 REST 아키텍처 스타일을 따르는 웹 서비스를 의미한다.

RESTful한 시스템은 REST의 원칙을 준수하여 설계된 시스템을 말한다.

RESTful API는 상태를 서버에 저장하지 않으며, 클라이언트가 필요한 모든 정볼;ㅡㄹ 요청에 포함해야 한다.

REST API 설계 규칙

RESTful 하기 위한 REST API 설계 규칙을 알아보자.

URI는 동사보다는 명사를, 대문자보다는 소문자를 사용해야 한다.

마지막에 슬래시 (/)를 포함하지 않는다.

언더바 대신 하이폰을 사용한다.

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

행위를 포함하지 않는다.

파일 확장자는 URL에 포함시키지 않는다.

전달하고자 하는 명사를 사용하되, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 사용한다.

URI에 작성되는 영어를 복수형으로 작성한다.

현재 진행하고 있는 프로젝트는 이러한 규칙이 적용되어 있지 않아, RESTful 하지 못하다.

또한, 레거시 프로젝트는 API 자체로 어떠한 의미를 가지는지 파악하기 힘들고 어떤 도메인의 API인지 일관성과 규칙이 없어서 직관적으로 이해하기가 어렵다.

GET, POST만을 이용해서 API가 작성되어 있기 때문인지, 행위를 URI에 포함시켜 작성해서 URI만 보고 어떤 API인지 이해하기가 어렵다.

이런 부분들이 합쳐져서 프론트 개발자와 협업이 힘들어지는 단점이 추가된다.

어떤식으로 수정?

이것을 백엔드단에서 프론트를 고려하지 않고 혼자서 처리하게 되면, 오히려 변경사항이 많아서 협업하기에 부정적인 결과를 만들어 낼 것으로 판단했다.

그래서 프론트 개발자와 함께 조금씩 도메인 별로 API를 수정해 나가는 것을 목표로 작업을 진행했다.

먼저 URI의 이름만 바뀌는 정도라면 프론트에서도 수정하는 코드의 양이 그리 많진 않다는 피드백을 받고 도메인 별로 API를 분류했다.

흩어져있던(서로 관련이 없던) API를 각 도메인으로 모으니 기능이 겹치는 API가 있기도 했다.

또한 API를 행위에 따라서 분류하기 편해져서 API 네이밍에 큰 도움이 되었다.

다음으론 자원의 행위에 따라 API를 수정했다.

GET과 POST로만 이루어진 API들을 PATCH, DELETE 등을 이용해서 수정해서 같은 URI라도 행위에 따라서 다른 API로 만들 수 있어서 깔끔한 형태의 API가 만들어 졌다.

예를 들어, GET /api/v1/members, POST /api/v1/members 이 두가지의 행위의 코드가 PATCH, DELETE를 추가해서 네 가지의 행위를 가진 API가 되어서 좀 더 효율적인 구조가 되었다.

마지막으로 API를 수정하고 Swagger와 Postman을 이용해서 API 명세를 작성하여 제공하는 방식으로 적용을 마무리 지었다.