[CS] REST API

박원준·2025년 10월 13일
CSRESTrestapi

🌐 REST API (Representational State Transfer API)

  • REST (Representational State Transfer)는 웹 서비스의 아키텍처 스타일 중 하나로, 웹에서 사용되는 자원을 효율적이고 안정적으로 사용할 수 있게 하는 기법입니다.
  • RESTful 웹 서비스는 HTTP를 기반으로 자원에 접근하는 방식을 정의합니다.
  • REST API는 웹에서 데이터를 주고받기 위한 아키텍처 스타일이며, 규칙(약속) 을 의미합니다.
  • 클라이언트와 서버 간의 통신을 단순화하고, 독립적인 시스템 간 상호 운용성을 높이는 핵심 기술입니다.

✅ REST API란?

  • 정의: HTTP 프로토콜을 기반으로, 자원을 URI로 표현하고 HTTP 메서드(GET, POST, PUT, DELETE 등)를 통해 자원을 다루는 방식.
  • 특징
    • 각 요청이 독립적(stateless) 으로 처리됨 → 서버 확장성과 유지보수성 향상
    • 구조가 단순하고 표준화되어 협업이 용이
    • 응답 데이터는 주로 JSON 형식을 사용
    • 다양한 플랫폼(웹, 모바일 등)에서 쉽게 활용 가능

🔹 REST의 구성 요소

구성 요소설명
Resource (자원)URI로 식별되는 대상 (예: /users/1)
Method (행위)HTTP 메서드를 통해 자원을 조작 (GET, POST, PUT, DELETE)
Representation (표현)자원의 상태를 JSON, XML 등으로 표현
Stateless (무상태성)각 요청은 독립적으로 처리되며, 서버는 이전 요청 정보를 저장하지 않음

🔹 HTTP 메서드 요약

메서드설명예시
GET자원 조회/users → 모든 유저 조회
POST자원 생성/users → 새 유저 등록
PUT자원 전체 수정/users/1 → ID 1 유저 정보 전체 수정
PATCH자원 일부 수정/users/1 → 이름만 수정
DELETE자원 삭제/users/1 → ID 1 유저 삭제

🔹 REST의 6가지 제약 조건 (RESTful 설계 원칙)

구성 요소설명
Client-Server 구조클라이언트와 서버는 서로 독립된 요소로 구성되어 있으며, 각각의 역할에 집중함으로써 클라이언트와 서버 간의 개발 및 확장성이 증가하고, 서로 간의 종속성이 줄어듦. (예: /users/1)
Stateless (무상태성)각 요청은 서버에게 모든 필요한 정보를 포함해야 하며, 서버는 클라이언트의 이전 요청에 대한 상태 정보를 저장하지 않음. 이로 인해 서버의 복잡성이 감소하고, 확장성이 향상됨.
Cacheable (캐시 처리 가능)클라이언트는 서버로부터 전달받은 응답을 캐시할 수 있어야 함. 캐싱을 통해 클라이언트와 서버 간의 통신 횟수가 줄어들며, 전체 시스템의 성능과 효율성이 향상됨.
Uniform Interface (일관된 인터페이스)REST는 일관된 인터페이스를 정의함으로써 상호작용의 단순화와 코드의 재사용성을 제공함. 유니폼 인터페이스의 원칙에는 리소스 식별, 자기 설명적 메시지, 하이퍼미디어를 통한 애플리케이션 상태 변경 등이 포함됨.
Layered System (계층화 시스템)시스템은 여러 계층으로 구성될 수 있으며, 각 계층은 독립적인 기능을 수행함. 이러한 구조를 통해 시스템의 유연성이 증가하며, 각 계층 간의 결합도가 낮아짐.
Code on Demand (선택적 코드 실행)필요한 경우 서버는 클라이언트에게 실행 가능한 코드를 제공할 수 있음. 이를 통해 클라이언트의 기능이 확장되며, 애플리케이션 로직의 일부를 서버에서 클라이언트로 이동할 수 있음. 하지만 이 원칙은 선택적이며, 모든 RESTful 시스템에서 적용되지는 않음.
  1. Client-Server 구조 → 역할 분리로 개발/배포 유연성 증가
  2. Stateless (무상태성) → 각 요청이 독립적으로 처리됨
  3. Cacheable (캐시 처리 가능) → 응답 데이터를 캐싱하여 성능 향상
  4. Uniform Interface (일관된 인터페이스) → 표준화된 URI/메서드 구조
  5. Layered System (계층화 시스템) → 프록시, 로드밸런서 등 중간 계층 허용
  6. Code-on-Demand (선택적 코드 실행) → 서버가 클라이언트에 스크립트 제공 가능 (거의 사용 X)

🔹 RESTful API란?

  • REST 원칙을 충실히 지킨 API를 의미.
  • 모든 요청이 명확한 목적과 일관된 규칙을 따라야 함.
  • RESTful하지 않은 예시:
    • /getAllUsers → ❌ (행위를 URI에 포함)
    • /users (GET 요청 사용) → ✅

🔹 실무 활용 예시

  • Spring Boot REST Controller 예시

    @RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        return ResponseEntity.ok(userService.findById(id));
    }

    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        return ResponseEntity.ok(userService.save(user));
    }
}

🔹 REST API vs SOAP API 비교

항목RESTSOAP
데이터 포맷JSON, XMLXML
상태 유지StatelessStateful 가능
전송 프로토콜HTTP 중심HTTP, SMTP 등 다양
학습 난이도쉬움복잡함
속도/유연성빠르고 유연느리고 무거움

🔹 REST API vs GraphQL 비교

항목REST APIGraphQL
데이터 요청 방식여러 엔드포인트에서 각각 요청단일 엔드포인트에서 원하는 데이터만 요청
Overfetching 문제필요 이상 데이터 수신 가능필요한 필드만 선택적으로 조회
Underfetching 문제여러 요청으로 데이터 조합 필요한 번의 요청으로 복수 자원 조회 가능
전송 프로토콜HTTP 기반 (GET, POST 등)HTTP 기반, 주로 POST 사용
응답 포맷JSON, XML 등 다양JSON 중심
버전 관리/api/v1/... 형태 필요스키마 확장으로 버전 불필요
캐싱HTTP 캐시 용이별도 캐시 로직 필요
도입 난이도쉬움, 표준화됨복잡함, 스키마 설계 필요

💡 예시 비교

✅ REST API 예시

GET /api/users/1
GET /api/users/1/posts

✅ GraphQL 예시

query {
  user(id: 1) {
    name
    posts {
      title
      likes
    }
  }
}

➡️ 한 번의 요청으로 유저 정보 + 게시글 데이터를 동시에 조회 가능

🔹 GraphQL의 장점

  • 데이터 최적화: 필요한 데이터만 선택적으로 수신 → 네트워크 효율 향상
  • 유연한 확장성: 백엔드 변경 없이 클라이언트에서 요청 구조 제어
  • 강력한 타입 시스템: 명확한 스키마 기반으로 안전한 요청 가능
  • 단일 엔드포인트 구조: /graphql 단일 엔드포인트로 통신 단순화

🔹 GraphQL의 단점

  • 캐싱 구현 복잡 (HTTP 표준 캐시 미사용)
  • 서버 부하 증가 가능 (복잡한 쿼리 요청 시)
  • 초기 세팅 복잡 (스키마 정의, 리졸버 구현 필요)

🔹 REST API 설계 시 주의할 점

  • URI는 명사형으로 작성 (예: /getUser ❌ → /users ✅)
  • HTTP Status Code를 올바르게 사용
    • 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error 등
  • 버전 관리: /api/v1/users 형태로 버전 구분
  • 보안 고려: HTTPS, JWT 인증, OAuth 등 적용

⚙️ HTTP 상태 코드 정리

범위의미주요 코드
1xx (정보)요청 진행 중, 임시 응답100 Continue
2xx (성공)요청이 성공적으로 처리됨200 OK, 201 Created, 204 No Content
3xx (리다이렉션)요청을 다른 위치로 이동301 Moved Permanently, 302 Found, 304 Not Modified
4xx (클라이언트 오류)클라이언트의 요청이 잘못됨400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
5xx (서버 오류)서버 처리 중 오류 발생500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable

🔹 자주 나오는 코드 설명

  • 200 OK: 요청 성공
  • 201 Created: 리소스 생성 성공 (POST 요청 시)
  • 204 No Content: 성공했지만 응답 본문 없음
  • 400 Bad Request: 요청 파라미터 또는 포맷 오류
  • 401 Unauthorized: 인증 실패 (JWT, OAuth 등)
  • 403 Forbidden: 권한 없음
  • 404 Not Found: 요청 리소스 존재하지 않음
  • 409 Conflict: 데이터 충돌 (중복된 요청 등)
  • 500 Internal Server Error: 서버 내부 오류
  • 503 Service Unavailable: 서버 과부하 또는 점검 중
profile
박원준
Hello
이전 포스트

[CS] 동기/비동기 처리

다음 포스트

[CS] Spring / Spring Boot

0개의 댓글