API가 뭔지 몰랐는데, 직접 만들어보니 요청과 응답이 보이기 시작했다
2026.08.13
1주차 때 업로드 하지 못했던 사례글을 뒤늦게 업로드 합니다. 양해 바랍니다.
API라는 말을 많이 들어봤지만, 막상 설명하려고 하면 조금 막연했습니다.
GET, POST, 200, 201 같은 용어도 각각의 뜻은 찾아볼 수 있었지만, 이것들이 실제 서버에서 어떻게 연결되는지는 직접 만들어보기 전까지 잘 와닿지 않았습니다.
이번에는 지피터스 23기 1주차 교안의 취미 API(hobby-api)를 참고해서 간단한 API 서버의 구조를 살펴보고, 소재를 바꿔 오늘 할 일을 관리하는 TODO API를 직접 만들어봤습니다.
교안에서는 취미를 다뤘습니다.
GET /hello→ 서버에서 인사말 받기GET /hobbies→ 취미 목록 가져오기POST /hobbies→ 새로운 취미 추가하기
제가 만든 것은 같은 구조에서 소재만 할 일로 바꿨습니다.
GET /todos→ 오늘 할 일 가져오기POST /todos→ 새로운 할 일 추가하기
처음에는 단순히 예제를 따라 만드는 정도라고 생각했습니다.
그런데 교안과 제가 만든 결과를 다시 비교해보는 과정에서 오히려 더 많은 것을 배웠습니다.
진행 방법
1. API를 세 덩어리로 이해해보기
교안에서 가장 이해하기 쉬웠던 부분은 서버를 복잡한 코드가 아니라 세 덩어리로 보여준 것이었습니다.
Client → Server → Data
요청 처리 저장
← JSON 응답
브라우저나 curl 같은 클라이언트가 요청을 보내면 서버가 요청을 처리하고, 필요한 데이터를 JSON으로 돌려줍니다.
직접 실행해보니 API가 조금 다르게 보이기 시작했습니다.
"API는 결국 요청을 보내고, 서버가 그 요청을 처리해서 약속된 형태로 응답하는 것이구나."
처음에는 어렵게 느껴졌던 개념이 실제 요청과 JSON 응답을 보니 훨씬 단순하게 느껴졌습니다.
2. GET으로 데이터를 가져와보기
교안에서는 다음과 같이 취미 목록을 가져옵니다.
curl localhost:3000/hobbies
그러면 서버에서 이런 형태의 JSON이 돌아옵니다.
{
"title": "오늘 뭐 하지? 취미 메뉴판",
"count": 3,
"menu": [
{
"id": 1,
"name": "클라이밍",
"mood": "몸 쓰고 싶은 날"
}
]
}
코드만 볼 때보다 curl로 직접 요청하고 응답을 확인하니 GET은 서버에 있는 것을 가져오는 요청이라는 것이 눈에 들어왔습니다.
3. POST로 데이터를 직접 추가해보기
다음은 취미를 하나 추가하는 요청입니다.
curl -X POST localhost:3000/hobbies \
-H "Content-Type: application/json" \
-d '{"name": "베이킹", "mood": "달달한 게 당기는 날"}'
서버는 새로운 데이터를 배열에 넣고 결과를 다시 JSON으로 보내줍니다.
{
"message": "\"베이킹\" 메뉴판에 추가 완료!",
"added": {
"id": 4,
"name": "베이킹",
"mood": "달달한 게 당기는 날"
}
}
여기서 GET과 POST의 차이도 좀 더 명확해졌습니다.
GET → 있는 데이터를 가져온다.
POST → 데이터를 보내 새로운 것을 만든다.
4. Claude Code와 ChatGPT를 활용해 TODO API로 바꿔보기
교안의 코드를 그대로 따라 하는 데서 끝내지 않고, Claude Code와 ChatGPT를 활용해 소재를 '취미'에서 '오늘 할 일'로 바꿔봤습니다.
교안:
GET /hobbies
POST /hobbies
제가 만든 API:
GET /todos
POST /todos
필수 데이터도 name에서 task로 바꿨습니다.
{
"task": "오늘 사례글 작성하기"
}
구조는 비슷하지만 직접 소재를 바꾸니 단순히 코드를 복사할 때와는 느낌이 달랐습니다.
어떤 부분은 그대로 두고, 어떤 부분을 내 목적에 맞게 바꿔야 하는지 생각하게 됐습니다.
AI가 코드를 만들어주는 것도 편리했지만, 더 유용했던 것은 만든 결과를 다시 교안과 비교하면서 차이의 이유를 확인하는 과정이었습니다.
5. 교안과 비교했더니 200과 201이 달랐다
TODO API는 잘 작동했습니다.
그런데 교안과 나란히 놓고 비교하다 보니 한 가지 차이가 눈에 들어왔습니다.
교안에서는 새로운 취미를 만들었을 때:
201 Created
제가 만든 TODO API에서는:
200 OK
를 반환하고 있었습니다.
둘 다 요청 자체는 성공했기 때문에 처음에는 별문제가 없어 보였습니다.
하지만 새로운 리소스를 생성한 요청에는 201 Created가 그 의미를 더 정확하게 표현한다는 것을 알게 됐습니다.
여기서 상태 코드가 단순히 "성공했다 / 실패했다"를 알려주는 숫자가 아니라는 것도 알게 됐습니다.
서버가 클라이언트에게
"요청을 잘 처리했어요."
라고 말하는 것과
"요청을 잘 처리했고, 새로운 데이터도 만들었어요."
라고 말하는 것은 다릅니다.
그 차이를 상태 코드가 표현해주는 것이었습니다.
6. 내가 추가한 기능에서 새로운 버그가 생겼다
더 재미있었던 것은 date 필드였습니다.
교안에는 날짜가 없었지만 TODO API에는 오늘 할 일을 다루기 위해 날짜를 추가했습니다.
그런데 오전에 실행해보니 날짜가 하루 전으로 표시되는 문제가 생겼습니다.
원인은 UTC 기준으로 날짜를 처리하고 있었기 때문이었습니다.
교안에는 없던 문제입니다.
제가 기능을 하나 더 추가했기 때문에 새롭게 생긴 문제였습니다.
처음에는 "왜 날짜가 어제지?" 싶었지만, 원인을 찾아보면서 중요한 것을 하나 배웠습니다.
예제에서 조금만 벗어나도 내가 해결해야 할 문제가 생긴다.
그리고 오히려 그때부터 학습이 더 재미있어졌습니다.
7. 서버를 껐다 켜면 데이터가 사라지는 이유도 이해했다
이번 서버에서는 데이터베이스 대신 JavaScript 배열에 데이터를 저장합니다.
const initial = [
{ id: 1, name: '클라이밍', mood: '몸 쓰고 싶은 날' },
{ id: 2, name: '필름 카메라 산책', mood: '혼자 걷고 싶은 날' },
{ id: 3, name: '보드게임', mood: '사람 만나고 싶은 날' },
];
처음에는 "데이터가 저장됐는데 왜 서버를 다시 켜면 없어지지?"라고 생각할 수도 있습니다.
하지만 이 배열은 DB가 아니라 서버가 실행되는 동안 메모리에 존재하는 변수입니다.
서버를 종료하면 추가했던 데이터도 사라집니다.
직접 데이터를 넣어보고 서버를 다시 시작해보니 메모리에 저장한다는 것과 DB에 영구적으로 저장한다는 것의 차이도 자연스럽게 이해할 수 있었습니다.
결과와 배운 점
API가 조금 덜 막연해졌다
이번 실습에서 가장 크게 얻은 것은 대단한 서버를 만든 것이 아닙니다.
오히려 API라는 것이 전보다 덜 막연해졌다는 것이 가장 큰 결과였습니다.
클라이언트가 요청한다
↓
서버가 요청을 받는다
↓
코드가 데이터를 읽거나 변경한다
↓
상태 코드와 JSON으로 응답한다
이 흐름을 직접 실행해봤다는 것이 중요했습니다.
따라 만드는 것보다 '하나 바꿔보기'에서 더 많이 배웠다
교안과 똑같이 취미 API를 만드는 데서 끝났다면 date 문제는 만나지 않았을 것입니다.
하지만 취미를 TODO로 바꾸고 날짜라는 기능을 하나 추가하면서 UTC 문제라는 예상하지 못한 문제를 만났습니다.
그리고 교안과 내 코드를 비교하지 않았다면 200과 201의 차이도 그냥 지나쳤을 가능성이 큽니다.
그래서 이번에 가장 기억에 남은 학습 방법은 이것입니다.
따라 만들기 → 하나 바꿔보기 → 결과 비교하기 → 차이의 이유 찾아보기
AI를 이용하면 예제를 빠르게 만들 수 있습니다.
하지만 AI가 코드를 만들어줬다는 것 자체보다, 그 결과를 원본과 비교하면서 "왜 다르지?"라고 질문하는 과정에서 더 많은 것을 배울 수 있었습니다.
에러 메시지도 API의 일부였다
또 하나 인상적이었던 부분은 잘못된 요청을 보냈을 때였습니다.
교안에서는 name을 빼먹으면 단순히 "오류입니다"라고 하지 않고 다음처럼 올바른 입력 예시까지 알려줍니다.
{
"error": "name은 꼭 필요해요. 예: { \"name\": \"베이킹\", \"mood\": \"달달한 게 당기는 날\" }"
}
이것을 보면서 좋은 API는 정상적으로 작동하는 것뿐만 아니라, 사용자가 잘못 요청했을 때 다음에 어떻게 해야 하는지도 알려줘야 한다는 점도 배웠습니다.
다음에는 DB까지 연결해보고 싶다
현재 TODO 데이터 역시 메모리 배열에 있기 때문에 서버를 다시 실행하면 사라집니다.
다음 단계에서는 DB를 연결해서 서버를 껐다 켜도 TODO가 남아 있게 만들어보고 싶습니다.
그리고 이번에 발견한 부분도 하나씩 개선해보려고 합니다.
생성 응답을
200 OK에서201 Created로 바꾸기날짜를 한국 시간 기준으로 정확하게 처리하기
메모리 배열 대신 DB에 저장하기
잘못된 요청에 이해하기 쉬운 에러 메시지 제공하기
처음부터 완벽하게 이해하고 만드는 것보다 작게 만들어보고, 문제가 생기면 그 이유를 하나씩 알아가는 방식이 저에게는 더 잘 맞았습니다.
API가 어렵게 느껴진다면 거창한 서비스부터 만들 필요는 없는 것 같습니다.
취미 목록이나 오늘 할 일처럼 작은 데이터 3개만 가지고도 충분합니다.
직접 GET 한 번 보내보고, POST 한 번 보내보면 그때부터 'API'라는 단어 뒤에 실제 동작이 보이기 시작합니다. 🌱
도움 받은 글
지피터스 23기 1주차
hobby-api교안




교안을 그대로 따라 만드는 데서 끝내지 않고 소재를 바꿔봤더니, 교안에는 없던 UTC 날짜 문제가 새로 생겼다는 부분이 특히 좋았어요. 예제를 벗어나는 순간 내가 해결해야 할 문제가 생긴다—그게 학습이 더 재미있어지는 지점이라는 것도요.
200 OK와 201 Created의 차이를 교안 비교로 발견하신 것도 인상적이었어요. "성공했다"와 "성공했고, 새로운 데이터도 만들었다"는 서버가 클라이언트에게 보내는 다른 메시지라는 설명—상태 코드가 단순한 숫자가 아니라 의미를 담은 언어라는 게 그 대비 덕분에 잘 들어왔습니다.
"따라 만들기 → 하나 바꿔보기 → 결과 비교하기 → 차이의 이유 찾아보기" 이 순서가 API 처음 배울 때만 아니라 어디에도 쓸 수 있는 방법인 것 같아요.
다음에 DB 연결해서 서버 껐다 켜도 TODO 살아있는 거 확인하시면, 또 작게 뭔가를 바꿔보셨을 때 어떤 새 문제가 생길지도 기대됩니다 🐈⬛