스터디 3주차 : API URL의 설계

25/3/31
UMC 동아리 8기 스프링 부트 스터디 3주차 API URL의 설계 & 프로젝트 세팅 부분을 진행하며, 공부했던 내용과 미션을 정리하는 포스트입니다.

📚 개념 정리

API

Application Programming Interface의 약자로, 말 그대로 애플리케이션을 프로그래밍할 때 쓰는 인터페이스이다. 추상화, 캡슐화의 개념이 적용되어 있어 실제 구현 방법은 몰라도 손쉽게 사용할 수 있도록 도와준다.

REST

REpresentational State Transfer의 약자로, HTTP를 기반으로 하여 웹에서 데이터를 주고 받는 서비스를 설계(웹 서비스 아키텍처)한 방식 중 하나를 의미한다.

REST의 원칙은 무상태성, 클라이언트-서버 구조, 캐시 가능성 등이 있는데 이 중 일부를 따르면 REST API, REST의 원칙을 조금 더 철저히 준수하면 RESTful API이다.
그러니까 모든 RESTful API는 REST API지만, 모든 REST API는 RESTful API는 아닌 관계인 것이다.
RESTful API가 되기 위해서는 다음과 같은 규칙을 지켜야 한다.
1. HTTP Method를 자원에 맞게 사용한다.
2. URI에 동사를 포함하지 않는다.
3. URI에서 단어의 구분이 필요한 경우 -(하이픈)을 사용한다.
4. 자원은 기본적으로 복수형으로 표현한다.
5. 단 하나의 자원을 명시적으로 표현하기 위해서는 식별 값을 사용한다.
6. 자원 간 연관 관계가 있을 경우 URI에 표현한다.

RobBagby 웹 API 디자인 모범 사례 - Azure Architecture Center를 읽으며 추가로 웹 API에 대해 공부해보았다.

위 문서는 HTTP REST API 설계에 중점을 두어 설명하였다. REST API는 플랫폼 독립성, 서비스 진화와 같은 특성을 가지고 있다. 플랫폼 독립성이란 표준 프로토콜을 사용해 구현하여 클라이언트 내부와는 관계 없이 어느 클라이언트든 사용할 수 있게 해야함을 말한다. 서비스 진화란 플랫폼 독립성과 비슷한 내용인데, 클라이언트와는 관계 없이 API가 독립적으로 기능 진화, 추가가 가능해야 한다. 그리고 모든 기능은 클라이언트가 사용할 수 있도록 검색이 가능해야 한다. 그리고 stateless, 무상태성이라는 특징을 가지고 있다. 각 HTTP 요청은 독립적이라 여러 요청 간에 정보를 저장하고 있으면 안 된다.
모범적인 웹 API를 디자인하기 위한 규칙들을 나열해보자면,
1. 복수 명사를 사용하되, 계층적 구조로 표현한다.
2. 쿼리 문자열을 통해 필터링, 정렬, 페이징을 지원한다.
3. HATEOAS(리소스를 위해 필요한 정보를 hyperlink로 반환하는 규칙)을 지킨다.
4. 버전을 관리하기 위해서는 URI, 쿼리 매개변수, 헤더, MIME 유형에 버전을 적어둘 수 있다.

💥 미션 및 해결 과정

❓ Soft Delete가 무엇인지 찾아보시고 soft delete에는 어떠한 HTTP Method가 들어가면 좋을지 적어주세요.

Soft Delete는 논리 삭제라고도 한다. 데이터를 완전히 삭제하는 것이 아닌, 복원이 가능하도록 status 등의 추가 데이터를 변경하여 저장해두는 것이다. 예시로는 계정을 삭제했을 때 즉시 delete하는 것이 아니라 deactivated boolean 값을 true로 변경하고 데이터를 유지하는 것이 있다. 데이터베이스의 용량이 커지고, select문을 사용할 때 추가적인 조건이 필요하나 복원이 가능하다는 점, 고객의 데이터는 가치가 있다는 점 때문에 사용된다.

반의어로는 Hard Delete(물리 삭제)가 있는데, 이는 데이터를 완전히 삭제하는 것을 의미한다. DELETE FROM ~ SQL문을 사용하여 구현하는 기능을 Hard Delete의 예시로 볼 수 있다.

Soft Delete를 구현할 때 HTTP Method는 어떤 걸 사용해야 할까? 즉시 생각나는 메소드는 Patch, Post, Delete로 세 가지였다. Patch와 Post는 데이터를 일정 부분 변경하는 것이므로 변경한 값을 보내는 걸로 Soft Delete를 구현할 수 있다. Delete는 프론트엔드 단에서는 삭제라고 알고 있기만 하면 되고, 메소드만 보아도 어떤 기능을 하는지 짐작이 가능하다는 장점이 있다.

하지만 Delete HTTP Method를 사용하면 Delete HTTP Method가 의도한 바와 약간 달라 문제가 되지 않을까? 라는 생각이 들었다. rfc7231에 따르면, Delete는 리소스를 완전히 제거했다는 의미가 아니라, 해당 URI와 연결된 기능을 더 이상 제공하지 않아 리소스에 접근이 불가능하다는 의미이다. 그러므로 soft delete를 위해 DELETE Method를 쓰는 것 역시 RESTful한 작업이다!

❓ 컨트롤 URI에 대해 조사해주시고 어떠할 때 사용이 가능한 지 예시를 들어 설명해주세요.

RESTful 설계에서는 명사를 사용하고 동사로는 HTTP Method를 사용해야 한다고 했지만, 컨트롤 URI는 동사를 직접 사용하여 특정 작업을 명시적으로 표현하는 것이다. 컨트롤 URI를 사용할 때는 RESTful 원칙과 균형을 맞춰야 하므로, 꼭 필요할 때만 사용해야 하고 프로젝트 내에서 일관성을 유지하는 것이 좋다.

플레이리스트에서 음악을 재생할 때 /playlist/play와 같이 단순한 CRUD 작업이 아니라 HTTP Method로 표현하기 힘든 경우에 사용할 수 있다. 혹은 클라이언트에서 특정 작업을 수행하도록 서버에 요청하고 싶을 때, 특정 상태로 전환을 할 때도 사용이 가능하다. 예시로 특정 유저가 체크아웃을 요청할 때 /users/{user-id}/checkout, 주문 취소 /orders/{order-id}/cancel가 있다.

💭 회고

정말 개발의 많은 것들이 객체지향설계의 추상화, 캡슐화의 개념을 포함하고 있어서 놀랐다. API가 이런 개념을 포함하고 있는 건 알고 있었는데, HTTP Method까지 추상화의 개념을 포함하고 있다니...

그리고 그동안 충분히 REST한 API를 설계하고 있었다고 생각했는데, 깊게 공부해보니 모르고 있던 부분도 있고 잘못 알고 있던 부분도 있었다 🥺 공부가 정말 끝이 없구나... 더 열심히 공부하는 수 밖에 없겠다 🤓