REST API

1. REST(Representational State Transfer)

  • 자원의 현재 상태(State)를 어떤 형식(Representation)으로 전달(Transfer)하는 규칙,방법

REST는 웹의 자원을 URI(주소)로 표현하고, HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용해 자원에 대한 CRUD 작업을 수행하는 아키텍처 스타일입니다. 이 방식을 사용하면, API의 URL과 HTTP 메서드만 보고도 어떤 기능을 하는지 쉽게 알 수 있습니다. 또한 웹 표준 프로토콜인 HTTP기반이기 때문에, 웹 브라우저, 모바일 앱, 서버 간 통신 등 다양한 환경에서 동일한 방식으로 호출할 수 있습니다.

2000년 로이 필딩(Roy Fielding)의 논문에서 소개되었습니다.

1) REST 예시

# POST - 사용자 생성
POST "http://localhost:8080/users"
body : {name:'hong'}

# GET - 전체 사용자 조회
GET "http://localhost:8080/users"

# GET - 특정 사용자 조회
GET "http://localhost:8080/users/1"

# PUT - 사용자 수정
PUT "http://localhost:8080/users/1"
{
  name: "hong"
}

# DELETE - 사용자 삭제
DELETE "http://localhost:8080/users/1"

2. REST의 핵심 개념

  • 자원(Resource)

    • 서버에 존재하는 모든 데이터(문서, 이미지, 사용자 정보 등)

    • REST는 모든 자원에 대해 고유한 URI(Uniform Resource Identifier)로 식별하는 것이 원칙

    • ex) : /users, /products/1

  • 표현(Representation)

    • 자원의 상태를 JSON, XML, HTML 등으로 표현

    • ex) GET /users/1 -> { "id": 1, "name": "mkm" }

  • 행위(Verb)

    • HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용하여 자원에 대한 행위를 정의하며, 메서드의 의미를 지켜서 사용해야 한다.

메서드
의미
예시

GET

자원 조회

GET /users

POST

자원 생성

POST /users

PUT

자원 수정(전체)

PUT /users/1

PATCH

자원 수정(일부)

PATCH /users/1

DELETE

자원 삭제

DELETE /users/1

3. REST의 6가지 제약 조건

REST 원칙
설명

인터페이스 일관성

URI, HTTP 등의 표준화된 방법을 사용한다.

클라이언트-서버 구조

클라이언트와 서버는 명확히 구분되어야한다.

무상태성

각 요청은 독립적으로 처리되고, 서버는 요청 상태를 저장하지 않는다.

캐시 처리 가능

응답은 캐싱이 가능해야한다.

계층화된 시스템

클라이언트는 서버와 직접 통신하지 않고, 중간 계층을 거쳐 요청을 전달한다.

코드 온 디맨드 (Optional)

서버는 클라이언트로 실행 가능한 코드를 전송할 수 있다.

4. REST API

REST API는 REST(Representational State Transfer) 아키텍처 스타일을 따르는 API를 의미합니다. 그리고 REST방식을 충분히 잘 준수한 서버를 RESTful API라고 부릅니다.

1) REST API 설계원칙

  1. 명사를 사용하여 리소스를 표현한다.

    1. (/getUsers ❌ → /users ✅) 동사가 아닌 명사 사용.

    2. 단수형 명사와 복수형을 같이 사용하는 경우 혼동을 주므로 복수형을 작성하는 것을 권장.

      1. /user/1 ❌ -> /users/1✅

  2. HTTP 메서드의 의미를한다 준수

    1. 데이터 조회는 GET , 저장은 POST, 삭제는 DELETE , 수정은 PUT/PATCH를 사용하여 작성한다.

    2. 단, 로그인과 같은 기능은 GET이 아닌 POST로 작성한다

      1. POST /auth/login

      2. POST /auth/logout

  3. 일관된 응답 구조를 가지도록 설계한다

    1. 계층적 구조를 표현한다.

    2. 1번 사용자의 주문 목록

      1. users/1/orders

    3. _대신 -를 사용한다.

      1. users/1/orders/{order-id}

    4. 조인 조건이 복잡한 경우, 최종적으로 조회할 리소스에 맞춰 URI는 단순화하고, 쿼리스트링을 사용하거나 BODY에 담아서 전달한다.(깊은 계층화는 지양) EX) 회원 → 주문 → 주문 상세 → 상품조회시

      1. GET /users/1/orders/2025/details/3/products/10❌

      2. GET /orders?userId=1&fromDate=2025-01-01&toDate=2025-02-01✅

  4. URI에 확장자를 표시하지 않는다.

    1. ex) 사용자 정보 요청시

      1. GET /users-accounts✅

      2. GET /users-accounts.json❌

  5. 쿼리 파라미터를 사용해 리소스를 필터링한다.

    • 새로운 API 생성을 지양하고, 쿼리 파라미터를 사용해 리소스를 필터링한다.

    • 올바른 예시

      • GET /users-accounts?status=active

      • GET /users-accounts?region=KR&age=30

  6. 응답일관성

    1. 응답에 대한 표준화된 성공/실패 상태코드를 작성한다.

      1. 200(갱신성공),201(생성성공),204(삭제성공),404,400,500

2) REST API vs MVC

구분
MVC 컨트롤러
REST 컨트롤러

응답 방식

HTML(View) 반환

JSON, XML 등 데이터 반환

어노테이션

@Controller + @ResponseBody

@RestController

사용 목적

웹 페이지 UI 렌더링

API 제공 (백엔드-프론트, 서버-서버 통신)

3) REST의 장점

  • URL과 HTTP 메서드만 보고 기능 예측 가능

  • HTTP 표준을 사용해 다양한 플랫폼에서 호출 가능

  • 무상태성으로 인해 서버 확장성 우수

4) REST의 단점

  • 요청마다 필요한 정보를 전부 보내야 하므로 데이터 중복 가능

  • 표준이 아닌 아키텍처 스타일이므로 구현 방식이 달라질 수 있음

5. POST MAN

브라우저 대신 요청을 보내고 응답을 눈으로 확인하면서 API를 테스트 할수 있도록 도와주는 도구.

https://www.postman.com/

PreviousSpringBootApplicationNextSwagger

Last updated