7장. API 및 DB 설계: 구조를 결정하라.①

RESTful API 설계 원칙

얼마 전 시범 삼아 글쓰기 앱을 만들려고 Claude Code에게 "블로그 같은 글쓰기 앱 만들어줘"라고 요청했다. 30분 만에 그럴듯한 코드가 나왔다. 텍스트 입력창, 저장 버튼, 목록 화면까지. 하지만 실제로 사용해 보니 문제가 속출했다. 이미지를 업로드하려니 어디에 저장되는지 모르겠고, 글 저장을 어디에 하는지 알 수 없었다.

문제는 내가 AI에게 제대로 된 설명을 하지 못했기 때문이었다. "글쓰기 앱"이라는 모호한 요청으로는 모호한 결과밖에 나올 수 없다. 마치 건축가에게 "집 좀 지어줘"라고 말하고 방 개수나 구조에 대한 설명 없이 기대하는 것과 같았다.

API와 DB 설계라고 하면 어려운 기술 용어처럼 들리지만, 실제로는 "앱이 어떻게 동작할지 미리 정하기"다. 요리에 비유하면 재료 준비와 조리 순서를 정하는 것과 같다. AI는 훌륭한 요리사지만, 무엇을 만들지는 우리가 알려줘야 한다.

RESTful API 설계 원칙

API는 "Application Programming Interface"의 줄임말이다. 쉽게 말하면 앱의 서로 다른 부분들이 대화하는 방법이다. 카페에서 주문하는 것과 비슷하다. 손님이 "아메리카노 한 잔"이라고 주문하면, 직원이 그에 맞는 음료를 만들어준다. 주문 방식이 정해져 있어야 혼란이 없다.

AI와 함께 API 기본 구조 만들기

글쓰기 앱에서 사용자가 할 수 있는 행동들을 먼저 나열해 보자. 이런 분석은 프로그래밍 지식이 없어도 할 수 있다. 일상적인 앱 사용 경험만 있으면 된다.

사용자는 이런 일들을 할 수 있어야 한다:

글을 쓰고 저장하기

내가 쓴 글 목록 보기

특정 글 불러와서 수정하기

글 삭제하기

이미지나 동영상 첨부하기