[Java 문법] REST API 이해하기

김홍기·2026년 4월 14일
Java 문법내일배움캠프

Java 문법

목록 보기
9/9

1. REST API 란?

  • REST 기반으로 서비스 API를 구현한 것

  • 리소스를 중심으로 URI를 설계하고 행위는 HTTP Method로 구분하는 방식

  • 요청과 응답은 일반적으로 JSON 또는 XML 형식

  • 아래 예시

    GET /items/123
    • items : 아이템이라는 리소스
    • 123 : 특정 아이템의 식별자
    • GET : 조회라는 행위

즉, REST API는 단순이 요청을 보내는 규칙이 아니라
자원을 어떻게 표현하고, 어떻게 다룰지에 대한 설계 방식

2. 왜 REST API 설계가 중요할까?

  • API는 혼자만 보는 코드가 아니며 모두가 API를 보고 이해 해야함
    • 프론트엔드 개발자
    • 다른 백엔드 개발자
    • 외부 시스템
    • 협업 팀원
  • 처음 보는 사람도 예측 가능한 API가 좋은 API
  • 아래 둘을 비교해 보자
POST /getItemList
POST /createItem
POST /deleteItem
GET /items
POST /items
DELETE /items/123
  • 두 방식 모두 구현은 가능하지만, 두 번째가 훨씬 더 직관적
  • URI는 리소스를 나타내고 Method가 행위를 설명함

다양한 이해관계자들이 이해해야 하기 때문에
URL + HTTP Method만 보고도 무슨 API인지 식별할 수 있어야함

3. API 요청(Request) 명세서

3-1. Method

HTTP Methd는 해당 요청이 어떤 행동을 하려는지 나타내는 동사 역할

MethodCRUD의미 (행동)
POSTCreate(새로) 생성하라.
GETRead(데이터를) 조회하라.
PUTUpdate(전체를) 수정하라. (또는 덮어써라)
DELETEDelete(데이터를) 삭제하라.
PATCHUpdate(일부만) 수정하라. (PUT과 달리 일부 필드만 변경)

3-2. Endpoint

Endpoint는 요청이 도달하는 주소, 행동의 대상이 되는 자원을 표현하는 경로

1) 구조

  • 보통 서버의 기본 주소(Base URL) 뒤에 붙는 URL 경로(Path) 의미
https://api.example.com + /items
  • 즉, 여기서 /items 가 엔드포인트

2) Endpont 작성 원칙

  • 동사보다 명사 사용

  • 가능하면 복수형으로 작성

  • 예시

    		GET /items
		GET /users
		GET /orders/1

  • 이렇게 쓰는 이유는 Endpoint가 "행동"보다 "대상 자원"을 표현해야하기 때문

    Endpoint 예시의미 (자원)
    /items'상품들(items)'이라는 자원 전체 (컬렉션)
    /items/123'상품들(items)' 중에서 '123번'이라는 특정 자원 1개
    /users'사용자들(users)'이라는 자원 전체
    /users/5/cart'5번 사용자'에게 종속된 '장바구니(cart)' 자원

  • 여기서 /users/5/cart 는 사용자라는 상위 자원 아래에 장바구니라는 하위 자원이 종속되어 있는 형태로 볼 수 있다.

3-3. 요청 파라미터 - 어떻게 데이터가 전달될까?

  • 데이터 전달 방식은 크게 3가지로 분류

1) Path Parameter

  • 특정 자원을 식별할 때 사용
    GET /items/123
DELETE /items/123
PATCH /items/123
  • 여기서 123은 특정 아이템을 식별하는 값

즉, Path는 "무엇을 대상으로 하는가"를 더 정확히 지정할 때 사용

2) Query Parameter

  • 조회 조건, 정렬, 페이지네이션 처럼 리소스에 대한 조건을 붙일 때 사용
GET /items?sort=new&page=2
GET /items?category=electronics

즉, Query는 "무엇을 조회할지"가 아니라 "어떤 조건으로 조회할지"를 표현하는데 적합

3) Request Body

  • 본문 데이터 자체를 담을 때 사용
  • 주로 POST, PUT, PATCH에서 많이 사용
  • 예를 들어 아래와 같은 요청을 보낼 수 있다.
{
  "name": "무선 마우스",
  "price": 35000,
  "category": "electronics"
}

GET은 일반적으로 Body를 사용하지 않는다고 이해하는 것이 좋다.

3-4. 요청 헤더

1) Content-Type

  • 보내는 Body의 형식을 명시

    Content-Type: application/json

"나는 지금 JSON 형식의 데이터를 보냅니다."라는 의미

2) Authorization

  • 인증 정보를 담을 때 사용

    Authorization: Bearer eyJhbGciOi...

로그인 후 발급받은 토큰 등을 전달할 때 자주 사용

4. API 응답(Response) 명세서

  • 응답을 보통 아래 3가지를 본다.
    • 상태코드
    • 응답 헤더
    • 응답 본문

4-1. 상태 코드(Status Code)

  • 상태 코드 : 요청의 성공/실패 여부를 알려주는 숫자

(1) 2xx : 성공 (Success)
200 OK: 조회(GET), 수정(PUT) 성공.
201 Created: 생성(POST) 성공.
204 No Content: 삭제(DELETE) 성공. (응답 Body가 없음)

(2) 4xx : 클라이언트 오류 (요청이 잘못됨)
400 Bad Request: 요청 자체가 잘못됨. (예: 필수 Body 값이 누락됨, JSON 문법 오류)
401 Unauthorized: 인증 실패. (예: 로그인이 필요함, 토큰이 유효하지 않음)
403 Forbidden: 권한 없음. (예: 로그인은 했으나, 관리자 기능에 접근 시도)
404 Not Found: 자원을 찾을 수 없음. (예: GET /items/9999처럼 없는 ID를 조회)

(3) 5xx : 서버 오류 (서버가 문제)
500 Internal Server Error: 서버 내부에서 오류 발생. (예: 코드 로직 오류, DB 연결 실패 등)

상태 코드는 단순 순자가 아니라 API 결과를 설명하는 신호

  • 예를 들어 생성 성공인데 무조건 200 OK만 주는 것보다, 201 Created를 반환하는 것이 의도를 더 잘 드러낸다.

4-2. 응답 헤더

  • 대표적으로 많이 보이는건 Content-Type

    Content-Type: application/json

즉, 서버가 지금 JSON 형식의 데이터를 돌려준다는 의미

4-3. 응답 본문

1) 단일 객체 조회

{
  "id": 123,
  "name": "무선 마우스",
  "price": 35000
}

2) 목록 조회

[
  {
    "id": 1,
    "name": "아이템 1"
  },
  {
    "id": 2,
    "name": "아이템 2"
  }
]

3) 조회 결과 없음

  • 조건에 맞는 데이터가 없더라도 오류가 아니라면 null 대신 빈 배열 반환하는것이 자연스러움
[]

4) 클라이언트 오류

{
  "message": "ID 9999에 해당하는 아이템을 찾을 수 없습니다."
}

5) 서버 오류

{
  "message": "요청을 처리하는 중 서버에서 오류가 발생했습니다."
}

5. REST API와 RESTful API 차이

  • 비슷하게 들리지만 완전히 같은 말로 쓰면 조금 애매하다.

  • REST : 아키텍처 스타일, 설계 철학

  • REST API : REST 방식을 기반으로 만든 API

  • RESTful API : REST 원칙을 비교적 잘 지킨 API

즉, 단순히 HTTP를 사용한다고 해서 모두 RESTful API가 되는 것은 아니다.

6. REST API 설계 시 자주 지키는 원칙

1) 소비자 입장에서 이해하기 쉬워야 한다

  • API는 만드는 사람보다 쓰는 사람이 이해하기 쉬워야 한다.

2) HTTP를 최대한 잘 활용해야 한다

  • Method, Header, Status Code를 의미에 맞게 사용해야 한다.

3) URI는 명사형, 가능하면 복수형이 좋다

  • /getUserList 보다 /users 가 더 REST스럽다.

4) 민감한 정보는 URI에 넣지 않는다

  • 비밀번호, 토큰, 개인정보는 URL보다 Header나 Body에 담는 것이 안전하다.

5) 예외 응답 형식은 일관되게 유지한다

  • API마다 에러 형식이 다르면 쓰는 쪽에서 불편하다.

7. URI 설계의 좋은 예와 아쉬운 예

❌ 아쉬운 예

POST /getItemList
POST /createItem
POST /updateItem
POST /deleteItem
  • 문제점
    • URI에 동사 사용
    • Method의 의미를 거의 활용하지 못함
    • API가 늘어날수록 일관성 저하

✅ 더 RESTful한 예

GET /items
GET /items/123
POST /items
PATCH /items/123
DELETE /items/123
  • 장점
    • URI는 리소스 표현
    • Method가 행위 표현
    • API만 봐도 의도가 더 잘 드러남

8. 에러 응답 형식은 왜 일관되어야 할까?

성공 응답만 잘 만드는 것으로는 부족하다.
좋은 API는 실패 응답도 일관성 있게 설계되어야 한다.

  • 예를 들어 API마다 아래와 같이 다르게 응답이 온다고 가정하자
    {
 "error": "잘못된 요청"
}
    {
"message": "Bad Request",
"code": 400
}
  • 응답 데이터를 사용하는 쪽에서는 처리가 불편하다.
  • 따라서 에러 응답 형식을 일정하게 맞추는 것이 좋다.
  • 예시
    {
  "timestamp": "2026-04-14T21:00:00",
  "status": 404,
  "error": "Not Found",
  "message": "해당 아이템을 찾을 수 없습니다.",
  "path": "/items/9999"
}
  • 이렇게 형식을 통일하면 좋은 점은 다음과 같다.
    • 프론트엔드에서 예외 처리하기 쉬움
    • 디버깅이 쉬움
    • API 전반의 일관성이 높아짐

9. Richardson 성숙도 모델

  • REST API 를 조금 더 깊게 이해하려면 Richardson Maturity Model도 같이 보면 좋다.
  • 이 모델은 API가 REST에 얼마나 가깝게 설계되었는지를 단계별로 나눈 것이다.

9-1. Level 0

하나의 엔드포인트에 모든 요청을 몰아넣는 단계

POST /api

  • Body 안에서 action으로 구분

    {
  "action": "getItem",
  "id": 123
}

9-2. Level 1

리소스별로 URI를 나누는 단계

POST /items
POST /users
  • 리소스는 구분했지만 Method 활용 부족

9-3. Level 2 (실무 최소 단계)

HTTP Method와 상태 코드를 의미에 맞게 사용하는 단계

GET /items
POST /items
PATCH /items/123
DELETE /items/123
  • 보통 실무에서 REST API라고 부를 때는 최소한 이 단계

9-4. Level 3

HATEOAS까지 포함한 단계

{
"id": 123,
"name": "무선 마우스",
"links": [
  {
    "rel": "self",
    "href": "/items/123"
  },
  {
    "rel": "update",
    "href": "/items/123"
  }
]
}
  • 응답 안에 다음 행동으로 이동할 수 있는 링크까지 포함
  • 보통 Level 2까지 활용하고, 상대적으로 덜 쓰이는 편

10. 마무리

  • REST API의 핵심은 결국 직관성, 일관성, 예측 가능성에 있다.
  • 좋은 RESTful API는
    • URI가 리소스를 잘 표현하고
    • HTTP Method가 행위를 설명하며
    • 상태 코드가 결과를 명확히 전달하고
    • 에러 응답 형식도 일관되게 유지된다

즉, RESTful API는 단순히 동작하는 API가 아니라 사용하는 사람이 이해하기 쉬운 API라고 볼 수 있다.

profile
김홍기
개발자 기록용
이전 포스트

[Java 문법] final 키워드

0개의 댓글