풀스택 백엔드 2026.06.15

[SECTION 09. REST API는 왜 등장했는가]

• REST(Representational State Transfer) = 2000년 로이 필딩(Roy Fielding)이 자신의 박사 논문에서 제안한 웹 아키텍처 설계 원칙. 로이 필딩은 HTTP 프로토콜 설계에도 참여한 사람으로, "HTTP를 제대로 활용하는 방법"을 정리한 것

• REST API = REST 원칙을 따르는 API(Application Programming Interface)
  = URL로 어떤 자원인지 표현하고, HTTP 메서드로 어떤 행동인지 표현하고, 데이터는 JSON으로 주고받는 방식

기존 방식:  서버가 HTML을 만들어서 줌  →  브라우저만 이해 가능
REST API:  서버가 데이터(JSON)만 줌   →  누구든 이해 가능
                                        (웹, 앱, IoT 등)

REST API가 해결한 것들

문제	REST API의 해결책
페이지 전체 새로고침	데이터만 받아서 필요한 부분만 업데이트
백엔드가 화면까지 담당	백엔드는 데이터만, 프론트엔드가 화면 담당
다양한 클라이언트 대응	JSON은 웹/앱/IoT 모두 이해 가능

---

REST API의 핵심 규칙

규칙 1: URL은 자원(Resource)을 표현한다

URL은 "무엇"을 다루는지 나타냅니다. 동사가 아닌 명사로 표현합니다.

❌ 나쁜 예 — URL에 동사 사용
/getMember
/createMember
/deleteMember?id=1
/getMemberList

✅ 좋은 예 — URL에 명사(자원) 사용
/members
/members/1
/members/1/orders

규칙 2: HTTP 메서드로 행동을 표현한다

"어떻게 할 것인지"는 HTTP 메서드로 표현합니다.

HTTP 메서드	행동	SQL 비유
GET	조회	SELECT
POST	생성	INSERT
PUT	전체 수정	UPDATE
PATCH	일부 수정	UPDATE (일부)
DELETE	삭제	DELETE

GET    /members       → 회원 전체 목록 조회
GET    /members/1     → 1번 회원 조회
POST   /members       → 새 회원 생성
PUT    /members/1     → 1번 회원 전체 수정
PATCH  /members/1     → 1번 회원 일부 수정
DELETE /members/1     → 1번 회원 삭제

기존 방식과 비교

기존: POST /deleteMember?id=1  → URL에 동사, 메서드는 POST
REST: DELETE /members/1        → URL은 명사, 메서드로 행동 표현

규칙 3: 데이터는 JSON으로 주고받는다

JSON(JavaScript Object Notation) 은 데이터를 표현하는 가벼운 형식입니다.

{
    "id": 1,
    "name": "홍길동",
    "email": "hong@example.com",
    "age": 25
}

JSON의 특징:

• 사람이 읽기 쉬움
• 모든 프로그래밍 언어에서 파싱 가능
• XML보다 훨씬 간결

<!-- XML 방식 — 장황하고 복잡 -->
<member>
    <id>1</id>
    <name>홍길동</name>
    <email>hong@example.com</email>
    <age>25</age>
</member>

// JSON 방식 — 간결하고 명확
{
    "id": 1,
    "name": "홍길동",
    "email": "hong@example.com",
    "age": 25
}

규칙 4: HTTP 상태 코드로 결과를 표현한다

200 OK           → 요청 성공
201 Created      → 생성 성공
400 Bad Request  → 잘못된 요청 (클라이언트 실수)
401 Unauthorized → 인증 필요 (로그인 안 됨)
403 Forbidden    → 권한 없음 (로그인은 됐지만 접근 불가)
404 Not Found    → 자원 없음
500 Internal Server Error → 서버 오류

---

섹션 정리

개념	핵심 내용
기존 방식의 문제	서버가 HTML까지 생성, 다양한 클라이언트 대응 어려움
REST	로이 필딩이 2000년 박사 논문에서 제안한 웹 설계 원칙
REST API	URL로 자원 표현, HTTP 메서드로 행동 표현, JSON으로 데이터 교환
JSON	가볍고 읽기 쉬운 데이터 표현 형식, XML보다 간결
HTTP 메서드	GET(조회), POST(생성), PUT(수정), DELETE(삭제)
HTTP 상태 코드	200(성공), 201(생성), 400(잘못된 요청), 404(없음), 500(서버 오류)
프론트/백 분리	백엔드는 REST API, 프론트엔드는 화면 담당

---

[SECTION 10. 스프링으로 REST API 만들기 — 게시판 API 실전]

@Controller vs @RestController

SECTION 08에서 @Controller 를 사용했습니다.

// @Controller — 뷰(HTML)를 반환
@Controller
public class PostController {

    @GetMapping("/posts")
    public String list(Model model) {
        model.addAttribute("posts", postList);
        return "posts/list"; // → templates/posts/list.html 렌더링
    }
}

REST API는 HTML이 아닌 JSON 데이터를 반환합니다.

// @RestController — JSON 데이터를 반환
@RestController
public class PostApiController {

    @GetMapping("/api/posts")
    public List<Post> list() {
        return postList; // → Java 객체를 JSON으로 자동 변환
    }
}

---

차이점 한눈에 보기

	@Controller	@RestController
반환값	뷰 이름 (String)	데이터 (객체, List 등)
응답 형태	HTML	JSON
사용 목적	화면 렌더링	REST API
구성	@Controller	@Controller + @ResponseBody

@RestController 는 @Controller + @ResponseBody 를 합친 것입니다.
@ResponseBody 가 붙으면 반환값을 뷰가 아닌 HTTP 응답 바디에 직접 씁니다.
Java 객체 → JSON 변환은 스프링이 내장한 Jackson 라이브러리가 자동으로 처리합니다.

---

핵심 어노테이션 정리

어노테이션	설명
@RestController	JSON 반환하는 컨트롤러
@RequestBody	HTTP 요청 바디의 JSON → Java 객체로 변환
@ResponseBody	Java 객체 → JSON으로 변환해서 응답
ResponseEntity	상태 코드 + 응답 바디를 함께 반환

---

hoppscotch으로 API 테스트하기

테스트 1. 전체 목록 조회

Method : GET
URL    : http://localhost:8080/api/posts

응답:

[
    {
        "id": 1,
        "title": "스프링 부트 시작하기",
        "content": "스프링 부트는 정말 편리합니다.",
        "author": "홍길동"
    },
    {
        "id": 2,
        "title": "REST API란 무엇인가",
        "content": "REST API에 대해 알아봅시다.",
        "author": "김철수"
    }
]

---

테스트 2. 단건 조회

Method : GET
URL    : http://localhost:8080/api/posts/1

---

테스트 3. 게시글 생성

Method  : POST
URL     : http://localhost:8080/api/posts
Headers : Content-Type: application/json
Body    : (raw - JSON)
{
    "title": "새 게시글",
    "content": "내용입니다.",
    "author": "박민준"
}

응답 상태 코드: 201 Created

---

테스트 4. 게시글 수정

Method  : PUT
URL     : http://localhost:8080/api/posts/1
Headers : Content-Type: application/json
Body    :
{
    "title": "수정된 제목",
    "content": "수정된 내용",
    "author": "홍길동"
}

---

테스트 5. 게시글 삭제

Method : DELETE
URL    : http://localhost:8080/api/posts/1

응답 상태 코드: 204 No Content

Postman에서 꼭 확인할 것

• HTML이 아닌 JSON 이 오는 것
• 상태 코드가 상황에 따라 200/201/204/404 로 다르게 오는 것
• 앞으로 스프링 서버는 화면을 몰라야 한다 — 데이터만 다룰 뿐

---

섹션 정리

개념	핵심 내용
@RestController	JSON을 반환하는 컨트롤러, @Controller + @ResponseBody
@RequestBody	요청 바디의 JSON → Java 객체로 자동 변환
ResponseEntity	HTTP 상태 코드와 응답 바디를 함께 반환
Jackson	Java 객체 ↔ JSON 자동 변환 라이브러리 (스프링 내장)
Postman	API 테스트 도구, 브라우저 없이 HTTP 요청 가능
fetch()	브라우저에서 API를 호출하는 JavaScript 함수
CORS	다른 출처에서 API 호출 시 브라우저 보안 정책