REST API

REST API는 "무엇을"은 주소로, "어떻게"는 GET·POST 같은 방법으로 나눠 부탁하는 API 규칙이에요. 도서관에서 책 번호(주소)를 대고 "빌릴게요·반납할게요"(방법)라고 말하는 것과 같아요.

글 서순명(솔리드그루 이사 · 퓨쳐인프라 운영) · 2026-10-29 작성 · 예시 서버와 요청은 2026-10-29 Windows 11(Node v24.15.0)에서 직접 실행

REST API는 어떻게 동작하나요?

REST(Representational State Transfer)는 로이 필딩이 2000년 박사 논문 5장에서 정리한 설계 원칙이에요(필딩 논문 5장). 데이터 하나하나를 "자원"으로 보고 주소를 붙이는 게 바탕이에요.

할 일 목록이라면 전체는 /todos, 1번 할 일은 /todos/1 이에요. 같은 주소에 방법만 바꿔 보내면 읽기·고치기·지우기가 돼요. 주고받는 내용은 대부분 JSON이에요. API가 뭔지부터 궁금하면 API 뜻을 먼저 보세요.

GET·POST·PUT·PATCH·DELETE는 뭐가 달라요?

"여러 번 보내도 데이터 상태가 같다"는 성질을 멱등이라고 해요. MDN 기준으로 GET·PUT·DELETE가 멱등이고 POST·PATCH는 아니에요(MDN HTTP 메서드). 결제 버튼을 두 번 눌렀을 때 두 번 결제되는 사고가 POST에서 나는 이유예요.

200·404 같은 숫자는 무슨 뜻이에요?

답에는 상태 코드가 붙어요. 첫 자리만 봐도 2는 성공, 4는 보낸 쪽 잘못, 5는 서버 잘못이에요.

뜻은 MDN 상태 코드 문서와 맞췄어요. 401이 뜨면 API 키부터 확인하면 돼요.

직접 만들어 보면 어떻게 나오나요?

2026-10-29 Windows 11 PC에서 Node v24.15.0으로 연습용 REST API를 직접 띄웠어요. 설치한 부품 없이 Node 기본 기능만 쓴 파일(todos.cjs) 하나예요. 핵심 부분은 이래요.

if (req.method === "GET" && !id) return send(res, 200, todos);
if (req.method === "POST" && !id) { const t = { id: nextId++, done: false, ...JSON.parse(raw) }; todos.push(t); return send(res, 201, t); }
if (req.method === "PATCH" && item) { Object.assign(item, JSON.parse(raw)); return send(res, 200, item); }
if (req.method === "DELETE" && item) { todos = todos.filter((t) => t !== item); return send(res, 204); }

그다음 curl(주소로 요청을 보내는 명령)로 차례대로 불렀어요.

$ curl -s localhost:18081/todos
[{"id":1,"text":"원두 주문","done":false}]  <- HTTP 200
$ curl -s -X POST localhost:18081/todos -d '{"text":"우유 사기"}'
{"id":2,"done":false,"text":"우유 사기"}  <- HTTP 201
$ curl -s -X PATCH localhost:18081/todos/1 -d '{"done":true}'
{"id":1,"text":"원두 주문","done":true}  <- HTTP 200
$ curl -s -X DELETE localhost:18081/todos/2
  <- HTTP 204
$ curl -s localhost:18081/todos/2
{"error":"없는 할 일이에요"}  <- HTTP 404
$ curl -s localhost:18081/todos
[{"id":1,"text":"원두 주문","done":true}]  <- HTTP 200
$ curl -s -X PUT localhost:18081/todos
{"error":"이 방법은 안 돼요"}  <- HTTP 405

• POST로 "우유 사기"를 보내자 2번이 생기고 201이 왔어요. PATCH는 1번의 done 칸 하나만 바꿨어요.
• 2번을 지우니 내용 없이 204만 왔어요. 다시 찾으니 404예요.
• 목록 주소에 PUT을 보내자 405가 왔어요. 이 서버는 목록 통째 바꾸기를 열어 두지 않았거든요.

REST API와 RESTful은 뭐가 달라요?

RESTful은 "REST 원칙을 잘 지킨"이라는 뜻의 형용사예요. 원래 REST에는 서버가 요청 사이에 상태를 기억하지 않기 같은 제약이 여럿 있어요. MDN은 이걸 다 지키지 않은 HTTP API도 흔히 RESTful이라 부른다고 적어 뒀어요(MDN Glossary: REST). 일상에서는 두 말을 거의 같은 뜻으로 써요.

주소는 어떻게 짓나요?

자주 하는 오해와 주의할 점

• "전부 POST로 해도 돌아가니 괜찮다" 돌아가긴 해요. 하지만 방법만 보고 읽기인지 쓰기인지 알 수 없어서, 다시 보내도 되는지 판단하기 어려워져요. 화면 코드와 서버가 서로 엉뚱하게 짤 위험도 커져요.
• "PUT과 PATCH는 같다" PUT은 통째 교체라 빠뜨린 칸이 지워질 수 있어요. 한 칸만 고칠 땐 PATCH예요.
• "성공이면 무조건 200" 만들기는 201, 지우기는 204처럼 나눠 주면 화면 코드가 결과를 정확히 알아요.

바이브코딩으로 화면과 서버를 따로 만들 때 이 표를 AI에게 같이 주면 서로 맞춰 짜요. 도구별 차이는 바이브코딩 툴 비교에 있어요.

퓨쳐인프라에서는 어떻게 쓰나요?

퓨쳐인프라 REST API의 기본 주소는 https://futureinfra.ai/v1 이에요. 콘솔 화면과 같은 API라서 서버·앱을 만드는 일도 주소와 방법으로 부를 수 있어요. 프로그램은 "Authorization: Bearer pk_live_…" 머리말로 API 키를 보내요.

키는 콘솔 API 키 화면에서 발급하고, 발급할 때 한 번만 보여 줘요. 키마다 권한과 월 한도를 따로 걸 수 있어요. 같은 기능은 MCP로 AI 에이전트가 쓸 수도 있어요.

자주 묻는 질문

REST API와 GraphQL은 뭐가 달라요?

REST는 자원마다 주소가 따로 있고, 정해진 모양의 답을 받아요. GraphQL은 주소 하나에 '이 칸들만 주세요'라고 골라 묻는 방식이에요. 처음 만드는 작은 앱이라면 자료와 예제가 많은 REST가 덜 헤매요.

REST API를 테스트하려면 뭘 써요?

터미널의 curl 명령으로 바로 보낼 수 있어요. 화면으로 하고 싶으면 Postman 같은 API 테스트 도구를 써요. AI 코딩 도구에 '이 주소들로 curl 테스트해 줘'라고 부탁해도 돼요.

REST API 문서는 어떻게 읽어요?

주소, 방법(GET·POST 등), 보내야 할 칸, 돌아오는 칸, 오류 번호 다섯 가지를 찾으면 돼요. 이 글의 방법 표와 상태 코드 표를 옆에 두면 대부분의 문서가 읽혀요.

주소 끝에 붙은 ?page=2 는 뭐예요?

쿼리 문자열이라고 해요. 같은 자원을 읽되 몇 쪽인지, 어떤 순서인지 같은 조건을 덧붙일 때 써요. 비밀번호나 개인정보는 주소에 넣지 않아요. 기록에 그대로 남기 때문이에요.

관련 용어

• API는 REST API가 속한 큰 개념이에요.
• JSON은 REST API가 주로 주고받는 글자 모양이에요.
• API 키는 401이 뜰 때 먼저 볼 것이에요.
• HTTP는 GET·POST와 상태 코드가 정의된 통신 규칙이에요.
• 백엔드는 REST API를 만들어 내주는 서버 쪽이에요.
• 404 에러는 자주 보는 '없음' 상태 코드예요.