RESTful API가 뭔가요? '프랜차이즈 카페 주문법' 비유로 3분 만에 완벽 정리!

안녕하세요, 여러분의 든든한 IT 길잡이 데브프리입니다.

 

이전 포스팅에서 API가 식당의 '메뉴판'과 같다고 설명해 드린 적이 있습니다. 백엔드 개발자가 메뉴판(API)을 만들어두면, 프론트엔드 개발자가 그 메뉴판을 보고 데이터를 주문하는 방식이죠.

 

그런데 개발자 채용 공고나 실무 기획서를 보면 그냥 API가 아니라 'RESTful API 설계 경험'이라는 단어가 끊임없이 등장합니다.

 

"API면 API지, 앞에 붙은 RESTful은 또 뭔가요?"

"주소에 동사를 쓰면 안 된다고요? 왜 그렇게 엄격하게 규칙을 정하는 거죠?"

 

오늘은 백엔드 개발자들의 전 세계 공통 약속이자, 깔끔한 서버 설계의 척도인 'RESTful API'의 개념과 핵심 설계 규칙을 '프랜차이즈 카페 표준 주문법'에 비유하여 아주 명쾌하게 정리해 드리겠습니다!

 

1. REST (Representational State Transfer) 란?

간단히 말해 REST는 '인터넷(HTTP) 상에서 데이터를 주고받을 때 지켜야 하는 전 세계 공통의 깔끔한 가이드라인'입니다. 이 가이드라인을 완벽하게 잘 지켜서 만든 API를 두고 우리는 'RESTful 하다'라고 부릅니다.

RESTful API는 전 세계 어디서든 똑같은 방식으로 소통하기 위해 만들어진 프랜차이즈 카페의 '표준 주문 매뉴얼'과 같습니다.

카페 주문 상황에 비유해 볼까요?

만약 주문 규칙(REST)이 없다면 손님(프론트엔드)들은 자기 마음대로 주문을 할 것입니다.

• "아이스 아메리카노 하나 주세요."
• "저기 까만 물 시원하게 한 잔 줘요."
• "커피. 차가운 거."

규칙이 없으면 바리스타(백엔드 서버)는 주문을 해석하느라 진땀을 빼게 됩니다. 심지어 바리스타가 바뀌면 주문을 아예 못 알아듣는 대참사가 일어납니다.

 

그래서 전 세계 개발자들은 약속을 했습니다. "우리 이제 데이터를 달라고 할 때, [음료 이름]과 [행동]을 철저하게 분리해서 표준 규격으로만 주문하자!" 이것이 바로 RESTful API가 탄생한 배경입니다.

 

2. RESTful API 설계의 2가지 핵심 황금 법칙

RESTful API를 설계할 때 지켜야 할 원칙은 여러 가지가 있지만, 실무에서 가장 중요한 '가독성'을 결정짓는 핵심 황금 법칙 2가지만 기억하시면 됩니다.

RESTful의 핵심은 목적지 주소(URI)에는 '무엇을(명사)' 처리할지만 적고, '어떻게(동사)' 할지는 HTTP 메서드에 온전히 맡기는 것입니다.

법칙 ①: 주소(URI)에는 오직 '명사(자원)'만 적는다! (동사 금지)

초보 개발자들이 가장 많이 하는 실수가 주소에 get, create, delete 같은 동사를 넣는 것입니다. REST 규칙에서 주소(URI)는 오직 내가 원하는 '대상(자원)'만을 가리켜야 합니다.

• 🚨 [나쁜 예 - 비표준]
  • http://devfree.com/getUsers (회원 목록 가져오기)
  • http://devfree.com/deletePost?id=5 (5번 게시글 삭제하기)
• ✅ [좋은 예 - RESTful]
  • http://devfree.com/users (회원이라는 자원 자체를 명시)
  • http://devfree.com/posts/5 (게시글 중 5번이라는 대상을 명시)

법칙 ②: 행동(동사)은 'HTTP 메서드(GET, POST, PUT, DELETE)'로 표현한다!

주소에서 동사를 뺐다면, 이제 "그래서 그 자원을 어쩌라고?"라는 질문이 남습니다. 이 행동을 결정하는 것이 바로 HTTP 메서드입니다. 데이터베이스의 CRUD(생성, 조회, 수정, 삭제)와 완벽하게 1:1로 매칭됩니다.

• C (Create): POST (데이터를 추가할 때)
• R (Read): GET (데이터를 달라고 할 때)
• U (Update): PUT / PATCH (데이터를 수정할 때)
• D (Delete): DELETE (데이터를 삭제할 때)

 

3. 실전 예시: 백엔드와 프론트엔드의 우아한 소통

이 두 가지 법칙을 합치면, 굳이 API 명세서를 꼼꼼히 읽지 않아도 주소와 메서드만 보고 "아~ 이 API가 무슨 역할을 하는구나" 하고 단숨에 예측할 수 있습니다.

• 회원 가입을 할 때
  • POST /users (유저 자원에 새로운 데이터를 생성해라!)
• 전체 회원 목록을 볼 때
  • GET /users (유저 자원들을 모두 보여달라!)
• 3번 회원의 정보를 볼 때
  • GET /users/3 (유저 자원 중 3번의 정보를 보여달라!)
• 3번 회원의 정보를 수정할 때
  • PUT /users/3 (유저 자원 중 3번의 정보를 덮어씌워라!)
• 3번 회원을 탈퇴(삭제)시킬 때
  • DELETE /users/3 (유저 자원 중 3번을 삭제해라!)

어떤가요? 주소는 모두 /users로 동일하지만, 앞에 붙은 HTTP 메서드가 바뀌는 것만으로 행동이 완벽하게 제어됩니다. 이것이 바로 RESTful API가 주는 예측 가능성과 우아함입니다.

 

4. 한눈에 비교하는 요약표

비교 항목	🚨 나쁜 설계 (Non-RESTful)	✅ 좋은 설계 (RESTful API)
자원 조회 (GET)	/getAllBoardList	GET /boards
특정 자원 조회 (GET)	/getBoard?id=1	GET /boards/1
새로운 자원 생성 (POST)	/createBoard	POST /boards
특정 자원 수정 (PUT)	/updateBoard?id=1	PUT /boards/1
특정 자원 삭제 (DELETE)	/deleteBoard?id=1	DELETE /boards/1

 

마무리

코드를 잘 짜는 것도 중요하지만, 내가 만든 코드를 '남들이 쉽게 이해하고 가져다 쓸 수 있게' 설계하는 것은 더 중요합니다.

 

프론트엔드 개발자에게 /deleteBoardUserPost 같은 근본 없는(?) API 주소를 건네주면 속으로 원망을 들을지도 모릅니다. 하지만 오늘 배운 RESTful 규칙에 맞춰 DELETE /boards/1 처럼 깔끔하게 설계해서 넘겨준다면, 여러분은 단숨에 "같이 일하고 싶은 센스 있는 백엔드 개발자"로 등극할 수 있습니다.

 

여러분이 지금 만들고 있는 토이 프로젝트의 API 주소창을 한 번 점검해 보세요. 혹시 주소창에 불필요한 동사가 섞여 있지는 않나요?

 

오늘의 데브 노트가 유익하셨다면 공감과 댓글 부탁드립니다. 지금까지 데브프리였습니다. 감사합니다!