0to1developer log
WIKIHTTP·REST API

프로젝트

플레이북

도구

AI

기본기

프론트

백엔드

인프라

플레이북

HTTP·REST API

브라우저와 서버가 주고받는 규칙, 그리고 REST.

HTTPREST API상태코드웹 기초백엔드 기초
프로토콜Java 개발자5분

한눈에

  • HTTP = 브라우저(앞)와 서버(뒤)가 주고받는 규칙 (요청-응답 한 쌍의 반복)
  • 메서드 = 무엇을 할지 (GET 조회 / POST 생성 / PUT·PATCH 수정 / DELETE 삭제)
  • URL = 대상(자원), 메서드 = 행위 (같은 /members/1도 GET·DELETE로 갈림)
  • 상태코드 = 결과 (2xx 성공 / 4xx 클라이언트 잘못 / 5xx 서버 잘못)
  • REST = 자원은 URL로, 행위는 메서드로 (URL에 getMember 같은 동사 안 넣음)
  • Spring 대응 = @GetMapping은 HTTP 메서드, @RestController는 REST API

식당을 떠올리면 거의 다 설명된다. 손님이 주문서를 건네면(요청) 주방이 음식을 내준다(응답). 주문서엔 "무엇을 원하는지"가 적혀 있고, 음식과 함께 결과도 딸려 온다 — 잘 나왔는지, 그런 메뉴가 없었는지, 주방에 불이 났는지. HTTP는 웹의 앞(브라우저)과 뒤(서버)가 이렇게 주고받는 규칙이다. 이 대화가 한 번 오가는 게 요청-응답 한 쌍이다.

요청과 응답

웹에서 벌어지는 일은 대부분 이 왕복 한 번의 반복이다. 브라우저가 서버에 "이거 주세요"라고 요청을 보내고, 서버가 결과를 담아 응답을 돌려준다. 한쪽이 묻고 한쪽이 답하는 단순한 구조라 이해하기 쉽다.

요청에는 두 가지가 꼭 들어간다. 무엇을 할지(메서드) 와 무엇에 대해(자원 주소, URL). "1번 회원을 조회" 같은 문장을 기계가 알아듣게 쪼갠 것이다.

메서드, 무엇을 할지

같은 자원(예: 회원)이라도 하려는 행위가 다르다. 그 행위를 정해진 동사로 표현한 게 메서드다.

  • GET — 조회. 그냥 가져다 본다. 아무것도 바꾸지 않는다.
  • POST — 생성. 새로 만든다.
  • PUT · PATCH — 수정. PUT은 통째로 갈아끼우고, PATCH는 일부만 고친다.
  • DELETE — 삭제. 지운다.

같은 /members/1 주소여도 GET이면 "1번 회원 보기", DELETE면 "1번 회원 삭제"다. 주소는 대상, 메서드는 행위로 나눠 생각하면 깔끔하다.

상태코드, 결과가 어땠는지

응답에는 세 자리 숫자가 붙는다. 주문이 어떻게 됐는지를 숫자 하나로 알려주는 것이다. 앞자리로 크게 나뉜다.

  • 2xx — 성공. 잘 처리됐다. 음식 제대로 나옴. (200 OK, 201 Created)
  • 4xx — 요청한 쪽(클라이언트) 잘못. 없는 메뉴를 시켰거나 주문서를 잘못 썼다. (404 Not Found 그 자원 없음, 400 Bad Request 요청이 이상함, 401·403 권한 문제)
  • 5xx — 서버(주방) 잘못. 주문은 멀쩡했는데 주방에 불이 났다. (500 Internal Server Error)

4xx인지 5xx인지만 봐도 "내 요청이 잘못됐나, 서버가 터졌나" 책임 소재가 갈려서 디버깅의 첫 갈림길이 된다.

REST: 자원을 URL로, 행위를 메서드로

REST는 이 HTTP를 깔끔하게 쓰는 약속이다. 핵심 한 줄은 이렇다. 다루려는 대상(자원)은 URL로 드러내고, 그 대상에 뭘 할지는 메서드로 표현한다. URL에 getMember, deleteMember 같은 동사를 넣지 않는다 — 동사는 메서드가 이미 맡고 있으니까.

이렇게 지키면 GET /members/1, DELETE /members/1만 봐도 무슨 뜻인지 바로 읽힌다. 주소가 스스로를 설명한다.

Spring으로 컨트롤러 짜본 사람 기준 다리

이미 다 써본 것들이다. 애너테이션 이름 뒤에 이 개념들이 있었던 거다.

@GetMapping·@PostMapping ↔ HTTP 메서드 — 같은 URL도 메서드로 조회/생성을 가름
@RestController ↔ REST API — 자원을 URL로 드러내고 JSON으로 주고받기
ResponseEntity.status(...) ↔ 상태코드 — 성공·실패를 숫자로 돌려주기
@PathVariable /members/1 ↔ 자원을 URL로 — 행위가 아니라 대상을 경로에 담기

Spring MVC로 REST 컨트롤러를 짜봤다면 이미 REST over HTTP를 하고 있었던 거다. @GetMapping("/members/{id}")가 "GET 메서드로 이 자원을 조회"라는 뜻이고, ResponseEntity.status(HttpStatus.NOT_FOUND)가 404를 돌려주는 일이다. 용어만 몰랐지 손은 이미 알고 있다.

요청 한 번의 왕복

GET /members/1 하나가 어떻게 흐르는지 따라가 보면 전체 그림이 잡힌다.

요청을 보낸다
GET /members/1 — 메서드 + 자원 주소
서버가 처리한다
해당 자원을 찾거나 만들거나 지움
상태코드로 결과를 알린다
200 성공 · 404 없음 · 500 서버 오류
본문(데이터)을 함께 준다
보통 JSON으로

우리 프로젝트에선

새김 AI의 FastAPI 백엔드가 프론트와 정확히 이 HTTP로 대화한다. 프론트가 요청을 보내면 백엔드가 JSON과 상태코드로 응답하는, 위에서 본 왕복 그대로다. Spring 대신 Python(FastAPI)일 뿐 REST 구조는 같다 — 자원을 URL로, 행위를 메서드로 나눈다. 자세한 건 새김 AI에.

그어봄의 MCP 서버도 도구(기능)를 HTTP로 바깥에 노출한다. AI가 쓸 수 있는 도구를 마치 API처럼 요청-응답으로 주고받는 셈이라, HTTP를 알면 이 구조가 낯설지 않다.

더 읽기

메서드·상태코드·REST를 비유와 예시로 더 풀어놓은 글들.