RestFul API

Lucel·2025년 5월 7일

restful api 애자일

StarLight

목록 보기

2/9

시작

안녕하십니까? 이번에 "RESTful API"라는 주제로
발표하게 된 팀 ST4R의 FE 개발자 안성준입니다

목차는 다음과 같이 구성되었으며 먼저 프로젝트 현황에 대해서 알아보고
오늘의 주제인 RESTful API에 대해 알아보는 시간을 가지도록 하겠습니다

프로젝트 진행상황

먼저 저희 ST4R의 프로젝트 진행 상황을 말씀드리겠습니다
현재 User Flow를 작성하였고, 프로세스 방식으로 애자일 방식을 도입하였습니다
이에 따라 기능 및 API 명세서와 ERD 역시 작성하였습니다

또한 본격적인 개발에 들어가기에 있어 공동 작업을 하기 위한
프론트엔드 개발 환경 설정이나 백엔드에서 배포 환경 구성까지 완료한 상태입니다

앞으로 스프린트 단위로 개발 우선순위를 정해서 프로젝트를 진행할 계획입니다

애자일?

그런데 애자일 방식이라고 하니 이 방식에 대해서 모르시는 분들도
있을 수 있다고 생각해서 아주 간단하게 설명을 해보고 넘어가보도록 하겠습니다

애자일 방식을 설명하기 위해서 폭포수방식과 비교해서 설명을 해드리겠습니다

먼저 폭포수 방식 일명 워터폴 방식입니다
예시를 들어보겠습니다
친구가 저에게 의자를 만들어달라고 부탁을 했습니다
그래서 저는 설계도를 그리고 재료를 사고 조립해서 완성시키고
친구에게 완성시켜서 의자를 보여줬습니다

이렇게 다 만들고 나서 보여주는 이런 방식을 우리는 폭포수 방식이라고 합니다
하지만 이러한 방식에는 단점이 존재합니다

만약 친구가 완성본을 보고 수정을 요청하면 처음부터 고쳐야하기 때문이죠
그래서 이를 보완하기 위한 방법으로 애자일 방식이 등장했습니다

애자일 방식은 폭포수 방식과는 다르게 중간중간 만들어서 보여주고
피드백을 받아서 만들어가는 방식을 이야기 합니다
이렇게 예시와 같이 한 단계씩, 자주 보여주면서 완성합니다

자 정리해보겠습니다
폭포수 방식은 처음에 모든 것을 계획하고 완성해나가는 방식이고
애자일은 조금씩 만들고 고쳐가며 진행하는 방식입니다

주제선정배경

그러면 다시 본 주제로 넘어와서 이야기해보도록 하겠습니다
저희는 이번주에 API 및 기능 명세서를 작성하였는데요
그 가운데 어떻게 하면 이를 잘 설계할 수 있을까?"
라는 고민을 하게 되었습니다

그래서 준비하게 되었습니다 저희 발표 주제 바로 RESTful API 입니다

RESTful API

먼저 RESTful API에서 API에 대해서 알아보겠습니다

API

API는 Application Programming Interface의 줄임말로
두 어플리케이션이 서로 통신하는 방법을 이야기 합니다
조금 더 쉽게 설명하기 위해서 그림을 통해서 설명해보겠습니다

이제 고객이 쌀국수 집을 갔는데 고수를 싫어해서
고수를 빼달라는 요청을 요리사에게 하고 싶어요

그래서 저는 주문서에 고수를 빼달라는 요청을 하였습니다
요리사는 이 주문서를 보고 요리를 할 때
쌀국수에 고수를 빼서 다시 고객에게 전달했습니다
외와 같은 주문서가 바로 API 입니다

클라이언트가 API를 통해 서버에게 데이터를 요청하고
서버는 그 요청받은 데이터를 다시 클라이언트에게 전달하게 됩니다
API에 대해서 알아봤는데 이제 다시 REST API가 무엇인지 알아보겠습니다

REST

REST는 HTTP 프로토콜을 통해 API를 설계하기 위한 스타일입니다

많은 책들이나 블로그, 유튜브를 보면
이 REST를 마치 택배 송장과 같다고 많이 비유를 하는데요

택배 송장을 보면 보내는 분과 받는 분이 있고
여기에는 성명 전화번호 주소를 적게 됩니다

이 송장처럼 REST는 어떤 곳에 어떤 것을
써야 할지에 대한 스타일이 정해져 있는 것입니다
바로 송장과 같은 것이 REST 입니다

그러면 REST API는 무엇일까요?
REST API는 앞서 설명한 REST 스타일을 잘 준수해서 만든 API 입니다
그러면 RESTful API는 뭘까요?

RESTful API는 REST의 설계 규칙을 잘 지키셔 설계된 API입니다
그래서 RESTful한 API를 보게되면 API 주소만 보고서도
어떤 데이터를 요청하고 있는지 알 수 있습니다

그리고 많은 사람들이 REST API와 RESTful API를 구분해서 사용하지 않고
공통된 단어로 사용하고 있습니다

다음은 REST API의 구성요소에 대해서 알아보겠습니다
이 REST API의 구성요소는 REST의 의미를 통해서 알 수 있는데요
REST의 의미를 보면 자원을 이름 즉 자원을 표현으로 구분해서
해당 자원의 상태를 주고받는 모든 것 즉 행위를 의미를 의미합니다

여기서 저희는 3가지 단어를 꼽을 수 있습니다 자원, 표현, 주고 받는 것 즉, 행위
일단 구성 요소의 첫 번째 자원에 대해서 알아보겠습니다

구성요소

자원은 해당 소프트웨어가 관리하는 모든 것을 뜻합니다
이 자원을 표현하는 방법에는 URI가 있습니다

그리고 두 번째 행위는 자원에 대한 행위로 그 자원을 표현하기 위한 이름입니다
표현 방법으로는 HTTP 요청 메서드가 있습니다

세 번째 표현은 자원에 대한 행위의 구체적인 내용으로
데이터가 요청되는 시점에서 자원의 상태를 전달합니다
표현 방법으로는 페이로드가 있습니다
이렇게 REST의 구성요소에 대해서 알아봤는데요

설계원칙

다음은 REST API의 설계 원칙에 대해서 알아보도록 하겠습니다
설계원칙 첫 번째는 "URI는 리소스를 표현해야 한다" 입니다
"두 번째는 HTTP 요청 메소드로 표현해야 한다" 입니다

이 HTTP 요청 메소드는 GET,POST,PUT과 PATCH,DELETE 등이 있고
이는 각각 조회 생성 수정 삭제를 나타냅니다

두 가지 설계 원칙을 잘 키셔 REST API를 만들기 위한
네이밍 컨벤션에 대해서 알아보도록 하겠습니다

네이밍 컨벤션

네이밍 컨벤션 첫 번째는 동사가 아닌 명사를 사용해야 합니다
showMovies와 같이 동사는 사용해서는 안되고 명사만을 사용해야 합니다
단, 컨트롤 자원을 의미하는 URI는 예외적으로 동사를 사용하는 것이 허용됩니다

다음 행위는 URL에 포함되지 않습니다
DELETE /movies/delete/1 과 같이 지금 delete가 중복되서 사용되고 있는데요
이렇게 중복성을 제거하고 DELETE는 또 동사이기 때문에
앞에 설명한 네이밍 컨벤션 원칙에서도 어긋나게 됩니다
그렇기에 DELETE /Movies/1과 같이 작성을 해야 합니다

그리고 소문자를 사용해야 하고

_(언더바) 대신 -(대시)를 사용해야 합니다

또한 파일 확장자는 포함하지 않고

마지막에 /(슬래시)는 포함하지 않습니다
마지막 슬래시는 아무 의미가 없는 것이기 때문에 포함하지 않습니다

이렇게 여러 네이밍 컨벤션에 대해서도 알아봤는데요
이번에는 제가 프론트엔드로써 어떻게 REST API를 사용해서
데이터를 요청하고 서버로부터 응답이 오는지에 대해서 알아보도록 하겠습니다

데이터 요청

저희는 데이터를 요청할 때 fetch() Axios jQuery 등을 사용할 수 있는데요
일단 내장된 브라우저의 API인 fetch()를 사용해서 확인해보도록 하겠습니다

API 명세서가 다음과 같이 있습니다
이 API는 회원을 생성하는 API이고 메서드는 POST로 하며
URI는 /members가 들어가고 Body에는 user_id와 name이 들어가게 됩니다
이 해당 API 명세서를 통해서 데이터를 요청해 보도록 하겠습니다

일단 fetch()의 첫 번째 인자로는 API의 주소를 입력해주면 됩니다
그래서 URI에 members가 담기게 되었고
두 번째 인자로는 HTTP 통신에 관한 내용이 담기게 됩니다
HTTP 메서드는 저희가 API 명세서 POST를 적어줬기 때문에 POST를 작성해주고
Header에는 Content-Type과 같이 요청의 성격이나 클라이언트에 대한 정보
그리고 요청을 처리하는 방식 등을 작성해주면 됩니다

그리고 Body에는 주고받을 데이터를 작성해주면 되고 이것을 JSON 형태로 넣어주면 된다

그리고 여기서 예외적으로 GET은 다음과 같은 축약 표현이 가능한데요
fetch()의 default 메서드가 GET이기 떄문에 가능한 것이고
만약에 요청을 할 때 Header에 특별하게 넣을게 없다면
두번째 인자는 모두 생략하고 첫번쨰 인자인 API 주소만 넣어주면 된다

서버 응답

서버 응답은 먼저 status code가 응답이 오는데요
번호에 따라 잘 데이터가 전달되고 왔는지를 확인할 수 있다
200번대는 성공을 의미하고, 300번대 리디렉션을 의미하고
400번대는 클라이언트 오류를 나타낸다, 보통 프론트쪽에서 오류가 났다는 뜻이다
500번대는 서버 오류를 의미하고, 보통 백엔드쪽에서 오류가 났다는 뜻이다

Header 데이터는 위에 비슷하게 HTTP 응답의 메타데이터를 이야기하고
Body에는 우리가 필요한 데이터가 담겨져있다