REST API 입문 가이드: 서버와 클라이언트가 데이터를 주고받는 기본 원리

추천캐릭터 2026. 6. 9. 20:43

728x90

웹 개발을 공부하다 보면 거의 반드시 만나게 되는 단어가 있습니다. 바로 REST API입니다.

프론트엔드에서 백엔드 서버로 데이터를 요청할 때도 REST API를 사용하고, 모바일 앱이 서버에서 회원 정보나 게시글 목록을 가져올 때도 REST API를 사용합니다. Spring Boot, Node.js, Django, FastAPI 같은 백엔드 프레임워크를 배울 때도 REST API는 기본 개념처럼 등장합니다.

하지만 처음 접하면 용어부터 헷갈릴 수 있습니다.

“API는 알겠는데 REST는 무엇일까?”
“REST API와 그냥 API는 다른 걸까?”
“GET, POST, PUT, PATCH, DELETE는 언제 다르게 써야 할까?”
“URI는 어떻게 설계해야 좋은 API라고 할 수 있을까?”

이번 글에서는 REST API를 처음 공부하는 사람도 이해할 수 있도록 서버와 클라이언트가 데이터를 주고받는 기본 원리를 정리해 보겠습니다.

REST API란?

REST API를 이해하려면 먼저 단어를 나누어 보는 것이 좋습니다.

REST API는 크게 두 부분으로 나눌 수 있습니다.

REST + API

API는 프로그램과 프로그램이 서로 대화하기 위한 통로입니다.
REST는 그 API를 설계하는 방식 중 하나입니다.

즉, REST API는 웹의 기본 규칙을 활용해서 자원을 중심으로 설계한 API라고 이해할 수 있습니다.

예를 들어 블로그 서비스가 있다고 가정해 보겠습니다.
블로그에는 게시글, 댓글, 회원 같은 데이터가 있습니다. 이런 데이터를 REST API에서는 “자원”으로 봅니다.

게시글 → posts
댓글 → comments
회원 → users

그리고 클라이언트는 이 자원에 대해 조회, 생성, 수정, 삭제 같은 요청을 보냅니다.

게시글 목록 조회
게시글 상세 조회
게시글 작성
게시글 수정
게시글 삭제

REST API는 이런 요청을 URI와 HTTP 메서드를 조합해서 표현합니다.

GET /posts
GET /posts/1
POST /posts
PATCH /posts/1
DELETE /posts/1

위 예시만 봐도 어느 정도 의미를 파악할 수 있습니다.

/posts는 게시글 자원을 의미하고, GET, POST, PATCH, DELETE는 그 자원에 대해 어떤 동작을 할지 나타냅니다.

API란 무엇인가?

API는 Application Programming Interface의 줄임말입니다.

조금 쉽게 말하면, API는 소프트웨어끼리 정해진 방식으로 데이터를 주고받기 위한 약속입니다.

예를 들어 사용자가 웹 브라우저에서 게시글 목록 페이지를 열었다고 해보겠습니다.
화면은 게시글 데이터를 직접 가지고 있지 않습니다. 그래서 백엔드 서버에 게시글 목록을 요청합니다.

클라이언트 → 서버: 게시글 목록 주세요
서버 → 클라이언트: 게시글 목록 데이터를 보내줄게요

이때 클라이언트가 서버에 요청하는 창구가 API입니다.

실제 요청은 다음처럼 표현할 수 있습니다.

GET /posts

서버는 요청을 처리한 뒤 JSON 형태의 데이터를 응답할 수 있습니다.

[
  {
    "id": 1,
    "title": "REST API 입문 가이드",
    "author": "admin"
  },
  {
    "id": 2,
    "title": "HTTP 상태코드 정리",
    "author": "admin"
  }
]

즉, API는 클라이언트와 서버가 대화하기 위해 미리 정해둔 문이라고 볼 수 있습니다.

REST란 무엇인가?

REST는 Representational State Transfer의 줄임말입니다.

용어만 보면 어렵지만, 핵심은 단순합니다.
REST는 웹에서 자원을 다루는 방식을 정리한 아키텍처 스타일입니다.

REST에서는 다음 관점이 중요합니다.

서버에는 자원이 있다.
자원은 URI로 표현한다.
자원에 대한 동작은 HTTP 메서드로 표현한다.
응답은 보통 JSON 같은 형식으로 전달한다.
요청과 응답은 일관된 규칙을 가진다.

예를 들어 회원 정보를 다루는 API를 생각해 보겠습니다.

GET /users
GET /users/10
POST /users
PUT /users/10
DELETE /users/10

여기서 /users는 회원 자원입니다.
그리고 앞에 붙은 HTTP 메서드가 동작을 나타냅니다.

REST의 핵심은 URI에 동작을 넣지 않는 것입니다.

다음과 같은 URI는 REST 스타일에 덜 적합합니다.

/getUsers
/createUser
/deleteUser

왜냐하면 get, create, delete 같은 동작이 URI에 들어가 있기 때문입니다.
REST 스타일에서는 URI는 자원을 표현하고, 동작은 HTTP 메서드로 구분하는 것이 일반적입니다.

더 REST에 가까운 방식은 다음과 같습니다.

GET /users
POST /users
DELETE /users/10

REST API의 핵심 구조

REST API는 보통 다음 세 가지 요소를 중심으로 설계합니다.

URI + HTTP 메서드 + 응답 데이터

각 요소를 하나씩 살펴보겠습니다.

1. URI는 자원을 표현한다

URI는 서버에 있는 자원의 위치나 이름을 표현합니다.

예를 들어 게시글을 다루는 API라면 다음처럼 만들 수 있습니다.

/posts
/posts/1
/posts/1/comments

각 URI의 의미는 다음과 같습니다.

URI의미

/posts	게시글 목록
/posts/1	1번 게시글
/posts/1/comments	1번 게시글의 댓글 목록

URI를 설계할 때는 동사보다 명사를 사용하는 것이 좋습니다.

좋은 예시는 다음과 같습니다.

/users
/orders
/products
/comments

아쉬운 예시는 다음과 같습니다.

/getUsers
/createOrder
/deleteProduct
/updateComment

REST API에서 URI는 “무엇을 다룰 것인가”를 나타내야 합니다.
“무엇을 할 것인가”는 HTTP 메서드가 담당합니다.

2. HTTP 메서드는 동작을 표현한다

HTTP 메서드는 자원에 대해 어떤 작업을 할지 나타냅니다.

대표적인 메서드는 다음과 같습니다.

메서드의미예시

GET	조회	게시글 목록 조회
POST	생성	새 게시글 작성
PUT	전체 수정	게시글 전체 수정
PATCH	일부 수정	게시글 제목만 수정
DELETE	삭제	게시글 삭제

같은 URI라도 메서드에 따라 의미가 달라집니다.

GET /posts
POST /posts

둘 다 /posts를 사용하지만 의미는 다릅니다.

GET /posts는 게시글 목록을 조회하는 요청입니다.
POST /posts는 새 게시글을 생성하는 요청입니다.

또 다음 예시를 보겠습니다.

GET /posts/1
PATCH /posts/1
DELETE /posts/1

모두 /posts/1이라는 같은 자원을 가리킵니다.
하지만 메서드에 따라 동작은 달라집니다.

요청의미

GET /posts/1	1번 게시글 조회
PATCH /posts/1	1번 게시글 일부 수정
DELETE /posts/1	1번 게시글 삭제

이처럼 REST API에서는 URI와 HTTP 메서드가 함께 의미를 만듭니다.

3. 응답 데이터는 주로 JSON을 사용한다

REST API에서 서버는 요청을 처리한 뒤 데이터를 응답합니다.
이때 가장 많이 사용되는 형식이 JSON입니다.

JSON은 JavaScript Object Notation의 줄임말입니다.
사람이 읽기 쉽고, 대부분의 프로그래밍 언어에서 쉽게 처리할 수 있습니다.

예를 들어 게시글 상세 조회 API는 다음과 같은 JSON을 응답할 수 있습니다.

{
  "id": 1,
  "title": "REST API 입문 가이드",
  "content": "REST API의 기본 개념을 정리합니다.",
  "author": "admin",
  "createdAt": "2026-06-25T10:00:00"
}

클라이언트는 이 JSON을 받아 화면에 표시합니다.

예를 들어 프론트엔드에서는 title 값을 화면 제목으로 보여주고, content 값을 본문 영역에 출력할 수 있습니다.

REST API 요청과 응답 흐름

REST API의 전체 흐름은 다음처럼 이해할 수 있습니다.

1. 클라이언트가 서버에 요청을 보낸다.
2. 서버는 URI와 HTTP 메서드를 보고 요청의 의미를 파악한다.
3. 서버는 필요한 비즈니스 로직을 처리한다.
4. 서버는 처리 결과를 JSON으로 응답한다.
5. 클라이언트는 응답 데이터를 화면에 표시한다.

예를 들어 게시글 목록을 조회하는 요청은 다음과 같습니다.

GET /posts HTTP/1.1
Host: example.com
Accept: application/json

서버는 게시글 목록을 조회한 뒤 다음과 같은 응답을 줄 수 있습니다.

[
  {
    "id": 1,
    "title": "REST API 입문 가이드"
  },
  {
    "id": 2,
    "title": "HTTP 메서드 정리"
  }
]

클라이언트는 이 데이터를 받아 게시글 목록 화면을 구성합니다.

REST API 설계 예시

간단한 블로그 API를 설계해 보겠습니다.

게시글 자원을 기준으로 다음 API를 만들 수 있습니다.

기능HTTP 메서드URI

게시글 목록 조회	GET	/posts
게시글 상세 조회	GET	/posts/{postId}
게시글 작성	POST	/posts
게시글 전체 수정	PUT	/posts/{postId}
게시글 일부 수정	PATCH	/posts/{postId}
게시글 삭제	DELETE	/posts/{postId}

댓글까지 포함하면 다음처럼 계층 구조를 만들 수 있습니다.

기능HTTP 메서드URI

특정 게시글의 댓글 목록 조회	GET	/posts/{postId}/comments
특정 게시글에 댓글 작성	POST	/posts/{postId}/comments
댓글 삭제	DELETE	/comments/{commentId}

여기서 중요한 것은 URI만 봐도 어떤 자원을 다루는지 어느 정도 예측할 수 있어야 한다는 점입니다.

/posts/1/comments는 1번 게시글의 댓글 목록이라는 의미가 분명합니다.
이런 방식은 API를 사용하는 개발자 입장에서 이해하기 쉽습니다.

좋은 URI 설계 규칙

REST API를 처음 설계할 때는 다음 규칙을 기억하면 좋습니다.

1. 명사를 사용한다

URI에는 동작보다 자원을 표현하는 명사를 사용합니다.

좋은 예:

/users
/orders
/posts

아쉬운 예:

/getUsers
/createOrder
/deletePost

동작은 HTTP 메서드가 담당하도록 설계하는 것이 좋습니다.

2. 복수형을 사용한다

자원 컬렉션은 보통 복수형으로 표현합니다.

/users
/posts
/products

물론 팀 규칙에 따라 단수형을 사용할 수도 있지만, 하나의 프로젝트 안에서는 규칙을 통일하는 것이 중요합니다.

3. 계층 관계를 표현한다

자원이 다른 자원에 포함되는 관계라면 URI에 계층 구조를 반영할 수 있습니다.

/users/10/orders
/posts/1/comments
/products/3/reviews

이 구조는 읽기 쉽습니다.

/posts/1/comments는 1번 게시글의 댓글이라는 의미가 자연스럽게 드러납니다.

4. URI는 소문자를 사용한다

URI는 보통 소문자를 사용합니다.

좋은 예:

/users
/order-items

아쉬운 예:

/Users
/OrderItems

대소문자가 섞이면 실수하기 쉽습니다.
따라서 일관되게 소문자로 작성하는 것이 좋습니다.

5. 단어 구분은 하이픈을 사용한다

여러 단어를 연결할 때는 하이픈을 사용하는 방식이 많이 쓰입니다.

/order-items
/user-profiles

언더스코어를 사용할 수도 있지만, REST API URI에서는 하이픈을 사용하는 규칙이 더 흔합니다. 중요한 것은 프로젝트 안에서 하나의 규칙으로 통일하는 것입니다.

HTTP 상태코드도 함께 설계해야 한다

REST API에서 응답 본문만 중요한 것은 아닙니다.
HTTP 상태코드도 함께 설계해야 합니다.

상태코드는 요청 결과를 숫자로 표현합니다.

자주 사용하는 상태코드는 다음과 같습니다.

상태코드의미사용 예시

200 OK	요청 성공	조회 성공
201 Created	생성 성공	회원가입, 게시글 작성
204 No Content	성공했지만 응답 본문 없음	삭제 성공
400 Bad Request	잘못된 요청	필수 값 누락
401 Unauthorized	인증 필요	로그인하지 않음
403 Forbidden	권한 없음	접근 권한 부족
404 Not Found	자원 없음	존재하지 않는 게시글
500 Internal Server Error	서버 오류	서버 내부 예외

예를 들어 게시글 작성에 성공했다면 다음처럼 응답할 수 있습니다.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 10,
  "title": "새 게시글"
}

반대로 존재하지 않는 게시글을 조회했다면 다음처럼 응답할 수 있습니다.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "message": "게시글을 찾을 수 없습니다.",
  "errorCode": "POST_NOT_FOUND"
}

상태코드를 올바르게 사용하면 클라이언트는 응답 본문을 모두 분석하지 않아도 요청 결과를 빠르게 판단할 수 있습니다.

GET과 POST의 차이

입문자가 가장 많이 헷갈리는 부분이 GET과 POST입니다.

간단히 정리하면 다음과 같습니다.

구분GETPOST

목적	데이터 조회	데이터 생성 또는 처리
데이터 전달	주로 쿼리 파라미터	주로 요청 본문
예시	게시글 목록 조회	게시글 작성
특징	같은 요청을 반복해도 보통 결과가 같음	서버 상태가 변경될 수 있음

GET은 조회에 사용합니다.

GET /posts
GET /posts?category=java
GET /posts/1

POST는 주로 생성에 사용합니다.

POST /posts
Content-Type: application/json

{
  "title": "REST API 입문",
  "content": "REST API를 쉽게 정리합니다."
}

GET 요청으로 데이터를 수정하는 방식은 피하는 것이 좋습니다.

예를 들어 다음과 같은 API는 좋지 않습니다.

GET /deletePost?id=1

조회 요청처럼 보이지만 실제로는 데이터를 삭제하기 때문입니다.
삭제는 다음처럼 DELETE 메서드를 사용하는 것이 더 적절합니다.

DELETE /posts/1

PUT과 PATCH의 차이

수정 API를 만들 때는 PUT과 PATCH도 자주 헷갈립니다.

둘 다 수정에 사용하지만 의미가 다릅니다.

구분PUTPATCH

의미	자원 전체 수정	자원 일부 수정
사용 예시	게시글 전체 내용 교체	제목만 수정
요청 데이터	전체 필드 전달 권장	변경할 필드만 전달

예를 들어 게시글 전체를 수정한다면 PUT을 사용할 수 있습니다.

PUT /posts/1
Content-Type: application/json

{
  "title": "수정된 제목",
  "content": "수정된 본문",
  "category": "Java"
}

반면 제목만 수정한다면 PATCH가 더 자연스럽습니다.

PATCH /posts/1
Content-Type: application/json

{
  "title": "수정된 제목"
}

실무에서는 팀 규칙에 따라 PUT과 PATCH를 구분하지 않고 하나만 사용하는 경우도 있습니다. 하지만 개념적으로는 전체 수정과 일부 수정을 구분해 두는 것이 좋습니다.

REST API와 JSON은 같은 개념일까?

REST API와 JSON은 같은 개념이 아닙니다.

REST API는 API를 설계하는 방식입니다.
JSON은 데이터를 표현하는 형식입니다.

즉, REST API가 반드시 JSON만 사용해야 하는 것은 아닙니다. XML, HTML, Text 등 다른 형식도 사용할 수 있습니다.

하지만 실무에서는 JSON을 가장 많이 사용합니다.
이유는 다음과 같습니다.

사람이 읽기 쉽습니다.
데이터 구조가 단순합니다.
JavaScript와 잘 맞습니다.
대부분의 언어와 프레임워크에서 쉽게 처리할 수 있습니다.
프론트엔드와 백엔드 사이에서 표준처럼 사용됩니다.

그래서 REST API를 공부할 때는 JSON 구조도 함께 익혀두는 것이 좋습니다.

REST API의 장점

REST API가 많이 사용되는 이유는 명확합니다.

1. 구조가 단순하고 이해하기 쉽다

URI와 HTTP 메서드만 봐도 어떤 요청인지 어느 정도 파악할 수 있습니다.

GET /users/1
DELETE /posts/10
POST /orders

이런 요청은 별도 설명이 많지 않아도 의미를 추측하기 쉽습니다.

2. HTTP 표준을 활용한다

REST API는 HTTP의 기본 구조를 활용합니다.

브라우저, 서버, 프록시, 캐시, 로드밸런서 같은 웹 환경과 잘 어울립니다.
또한 HTTP 상태코드, 헤더, 메서드 같은 기존 규칙을 활용할 수 있습니다.

3. 프론트엔드와 백엔드 협업에 좋다

프론트엔드와 백엔드가 API 규칙을 정해두면 서로 독립적으로 개발하기 쉽습니다.

예를 들어 백엔드는 다음 API를 제공한다고 문서화합니다.

GET /posts
POST /posts
GET /posts/{postId}

프론트엔드는 이 규칙에 맞춰 화면을 개발할 수 있습니다.

4. 테스트와 문서화가 쉽다

REST API는 Postman, Swagger, curl 같은 도구로 테스트하기 쉽습니다.

요청 URL, 메서드, 헤더, 본문, 응답 예시를 문서화하면 API 사용자가 쉽게 이해할 수 있습니다.

REST API의 한계

REST API가 항상 완벽한 방식은 아닙니다.

다음과 같은 한계도 있습니다.

1. 복잡한 조회 조건은 URI가 길어질 수 있다

검색 조건이 많아지면 URI가 복잡해질 수 있습니다.

GET /posts?category=java&keyword=spring&sort=createdAt&page=1&size=20

이 정도는 괜찮지만 조건이 지나치게 많아지면 관리가 어려워질 수 있습니다.

2. 모든 상황을 자원 중심으로 표현하기 어렵다

실무에서는 단순 CRUD가 아닌 복잡한 행위가 많습니다.

예를 들어 다음과 같은 기능은 URI 설계가 애매할 수 있습니다.

주문 결제하기
이메일 인증하기
비밀번호 재설정하기
쿠폰 발급하기
파일 변환 요청하기

이런 경우에는 REST 원칙을 완벽하게 맞추기보다 팀이 이해하기 쉬운 일관된 규칙을 정하는 것이 중요합니다.

3. 과도한 REST 순수성은 실무에 맞지 않을 수 있다

REST 원칙을 지나치게 엄격하게 적용하면 오히려 API가 복잡해질 수 있습니다.

실무에서는 보안, 프레임워크 구조, 레거시 시스템, 프론트엔드 요구사항 때문에 일부 규칙을 유연하게 적용하기도 합니다.

중요한 것은 “REST를 100% 지키는 것”이 아니라, 예측 가능하고 일관된 API를 만드는 것입니다.

REST API 설계 체크리스트

REST API를 처음 설계할 때는 다음 항목을 확인하면 좋습니다.

URI가 자원을 명확하게 표현하는가?
URI에 불필요한 동사가 들어가 있지 않은가?
HTTP 메서드를 목적에 맞게 사용했는가?
성공과 실패 응답 형식이 일관적인가?
HTTP 상태코드를 적절하게 사용했는가?
요청 예시와 응답 예시를 문서화했는가?
네이밍 규칙이 프로젝트 전체에서 통일되어 있는가?
프론트엔드가 이해하기 쉬운 구조인가?
에러 메시지와 에러 코드가 명확한가?
인증과 권한이 필요한 API를 구분했는가?

이 체크리스트를 기준으로 설계하면 초보자도 훨씬 안정적인 API를 만들 수 있습니다.

Spring Boot에서 REST API는 어떻게 연결될까?

Spring Boot에서는 Controller를 통해 REST API를 만들 수 있습니다.

예를 들어 게시글 목록 조회 API는 다음처럼 작성할 수 있습니다.

@RestController
@RequestMapping("/posts")
public class PostController {

    @GetMapping
    public List<PostResponse> getPosts() {
        return List.of(
                new PostResponse(1L, "REST API 입문"),
                new PostResponse(2L, "HTTP 상태코드 정리")
        );
    }
}

위 코드는 다음 요청에 응답합니다.

GET /posts

게시글 상세 조회 API는 다음처럼 만들 수 있습니다.

@GetMapping("/{postId}")
public PostResponse getPost(@PathVariable Long postId) {
    return new PostResponse(postId, "REST API 입문");
}

이 코드는 다음 요청에 응답합니다.

GET /posts/1

게시글 작성 API는 다음처럼 만들 수 있습니다.

@PostMapping
public PostResponse createPost(@RequestBody PostCreateRequest request) {
    return new PostResponse(10L, request.title());
}

이 코드는 다음 요청에 응답합니다.

POST /posts
Content-Type: application/json

{
  "title": "새 게시글",
  "content": "본문 내용입니다."
}

이처럼 Spring Boot의 @GetMapping, @PostMapping, @PatchMapping, @DeleteMapping은 REST API의 HTTP 메서드와 직접 연결됩니다.

자주 묻는 질문

Q1. REST API는 백엔드 개발자만 알아야 하나요?

아닙니다. 프론트엔드 개발자, 모바일 앱 개발자도 알아야 합니다.
클라이언트가 서버와 통신할 때 REST API를 자주 사용하기 때문입니다.

Q2. REST API는 무조건 JSON을 써야 하나요?

아닙니다. REST API는 설계 방식이고 JSON은 데이터 형식입니다.
하지만 실무에서는 JSON을 가장 많이 사용합니다.

Q3. URI에 동사를 쓰면 안 되나요?

무조건 금지는 아닙니다. 하지만 REST 스타일에서는 URI에 동작보다 자원을 표현하는 명사를 사용하는 것이 좋습니다.
동작은 HTTP 메서드로 구분하는 편이 더 일관적입니다.

Q4. REST API를 완벽하게 지켜야 하나요?

실무에서는 완벽한 REST보다 일관성이 더 중요합니다.
팀원들이 이해하기 쉽고, 클라이언트가 예측 가능하며, 문서화하기 쉬운 API가 좋은 API입니다.

Q5. REST API를 공부한 다음에는 무엇을 배우면 좋을까요?

다음 주제를 이어서 공부하면 좋습니다.

HTTP 상태코드
쿠키와 세션
JWT 인증
CORS
Spring Boot Controller
API 예외 처리
Swagger 또는 OpenAPI 문서화
Postman을 이용한 API 테스트

REST API는 단독 개념이 아니라 웹 개발의 여러 개념과 연결됩니다.
기본 구조를 이해한 뒤 HTTP, 인증, 보안, 문서화까지 확장해서 공부하는 것이 좋습니다.

마무리

REST API는 서버와 클라이언트가 데이터를 주고받기 위한 대표적인 설계 방식입니다.

핵심은 다음과 같습니다.

자원은 URI로 표현합니다.
동작은 HTTP 메서드로 구분합니다.
데이터는 주로 JSON으로 주고받습니다.
요청 결과는 HTTP 상태코드로 함께 표현합니다.
API 이름과 응답 구조는 일관되게 설계해야 합니다.

REST API를 처음 공부할 때는 용어가 어렵게 느껴질 수 있습니다. 하지만 본질은 단순합니다.

클라이언트가 서버에 원하는 자원을 요청하고, 서버가 정해진 형식으로 응답하는 약속입니다.

이 개념을 이해하면 Spring Boot Controller, 프론트엔드 fetch 요청, 모바일 앱 서버 통신, API 문서화, 인증 처리까지 훨씬 자연스럽게 연결됩니다.

REST API는 웹 백엔드 개발의 기본기입니다.
처음부터 완벽하게 설계하려고 하기보다 URI, HTTP 메서드, JSON 응답, 상태코드의 역할을 정확히 구분하는 것부터 시작하면 됩니다.

728x90

저작자표시 비영리 (새창열림)