RESTful API란 무엇인가요?

김상욱·2024년 12월 4일

RESTful API란 무엇인가요?

RESTful API는 웹 서비스 개발에서 널리 사용되는 아키텍처 스타일인 REST(Representational State Transfer)의 원칙을 따르는 애플리케이션 프로그래밍 인터페이스입니다. Restful API는 웹의 기존 기술과 프로토콜을 활용하여 클라이언트와 서버 간에 데이터를 교환하는 효율적이고 확장 가능한 방법을 제공.

API는 'Application Programming Interface'의 약자로 서로 다른 소프트웨어 시스템 간에 상호 작용할 수 있도록 해주는 인터페이스를 의미합니다. API는 하나의 애플리케이션이 다른 애플리케이션의 기능이나 데이터를 사용할 수 있도록 정의된 메서드, 프로토콜, 도구의 집합입니다.

REST는 'Representational State Transfer'의 약자로 핵심 개념은 자원(Resource)의 표현(Representation)을 전송(Transfer)하는 것입니다. 여기서 자원은 URI(Uniform Resource Identifier)로 식별되며 클라이언트와 서버는 이 자원의 상태를 전송하고 조작합니다.

Restful 아키텍처 제약 조건 6가지
1. 클라이언트-서버 아키텍처(Client-Server Architecture) : 클라이언트와 서버는 서로 독립적으로 개발되고 배포됩니다. 서버는 데이터 저장 및 비즈니스 로직을 처리하고 클라이언트느 사용자 인터페이스 및 사용자 경험에 집중.
2. 무상태성(Statelessness) : 서버는 각 요청을 완전히 독립적으로 처리하며, 이전 요청의 상태를 유지하지 않습니다. 모든 필요한 정보는 요청 자체게 포함되어야 합니다.
3. 캐시 가능성(Cacheability) : 응답은 캐시될 수 있어야 하며, 서버는 응답에 캐시 가능한지 여부를 나타내는 적절한 메타데이터를 포함해야 합니다. 캐싱은 네트워크 트래픽을 줄이고 응답 시간을 향상시킵니다.
4. 통합된 인터페이스(Uniform Interface) : 시스템의 각 부분이 동일한 부분으로 통신할 수 있도록 합니다.
-> 4가지 제약 조건 포함

  • 각 자원은 고유한 URI로 식별됩니다.
  • 자원은 다양한 포맷(JSON, XML 등)으로 표현될 수 있습니다.
  • 클라이언트는 자원의 표현을 사용하여 그 자원을 수정할 수 있습니다.
  • 각 메시지는 필요한 모든 정보를 포함하여 독립적으로 이해될 수 있어야 합니다.
  1. 계층형 시스템(Layered System) : 클라이언트는 중간 계층(ex - 프록시, 게이트웨이)을 통해 서버와 통신할 수 있습니다. 각 계층은 특정 기능(보안, 로드 밸런싱 등)을 수행할 수 있습니다.
  2. 코드 온 디맨드(Code on Demand) : 서버는 클라이언트에게 실행 가능한 코드를 전송하여 기능을 확장할 수 있습니다.

RESTful API란 위에서 설명한 REST 원칙과 제약 조건을 따르는 API를 의미. HTTP 프로토콜을 사용하여 클라이언트와 서버 간에 데이터를 교환하며 일반적으로 JSON이나 XML 같은 포맷을 사용.

주요 구성 요소
1) 자원(Resource) : 모든 자원은 고유한 URI로 식별
ex) /users, /users/123
2) HTTP 메서드(HTTP Methods) : HTTP 메서드를 사용하여 자원에 대한 CRUD 작업 수행
GET : 자원 조회
POST : 새로운 자원 생성
PUT : 기존 자원을 완전히 대체
PATCH : 기존 자원의 일부를 수정
DELETE : 자원을 삭제
3) HTTP 상태 코드 (HTTP Status Codes)
서버는 요청에 대한 결과를 HTTP 상태 코드를 통해 클라이언트에게 알립니다.
200 OK : 요청 성공적 처리
201 Created : 새로운 자원이 성공적으로 생성
400 Bad Request : 잘못된 요청
401 Unauthorized : 인증 필요
404 Not Found : 요청한 자원을 찾을 수 없음
500 Internal Server Error : 서버 내부 오류
4) 데이터 포맷(Data Format)
Restful API는 데이터의 표현을 위해 일반적으로 JSON이나 XML 사용

장점
확장성(Scalability) : 서버는 클라이언트의 상태를 유지하지 않으므로 수평적으로 확장하기 쉽다. 캐시를 통해 서버 부하를 줄이고 성능 향상 가능
독립적인 개발(Independent Development) : 클라이언트와 서버가 독립적으로 개발 및 업데이트될 수 있습니다. RESTful API는 다양한 클라이언트에서 사용할 수 있습니다.
표준화된 인터페이스(Standarized Interface) : HTTP 메서드와 상태 코드를 사용하여 일관된 방식으로 통신. 표준을 따르므로 다양한 시스템과 쉽게 통합.
가벼움(Lightweight) : SOAP같은 프로토콜에 비해 메시지 구조가 단순하여 오버헤드가 적음. 필요한 데이터만 전송하여 네트워크 사용 최적화.

단점
표준의 부재(Lack of Standard) : REST는 아키텍처 스타일로 구체적인 표준이 없기 때문에 구현 방법이 다양. 개발자마자 다른 해석을 할 수 있어 API의 일관성이 떨어질 수 있음
복잡한 쿼리 지원의 제한(Limited Support for Complex Queries) : 여러 자원을 조합하거나 복잡한 검색을 수행하기 위해서는 추가적인 설계 필요. 필요한 데이터보다 더 많은 데이터를 가져오거나 원하는 데이터를 모두 가져오지 못할 수 있음.
보안 이슈(Security Issues) : 무상태성으로 인해 클라이언트는 매 요청마다 인증 정보를 제공해야 하므로 보안에 취약할 수 있다. HTTPS를 사용하지 않으면 민감한 데이터가 노출될 위험이 있다.

RESTful API에 대해 신입 및 취업 준비 중인 Java, Spring 백엔드 개발자 입장에서 실습해볼 만한 과제나 프로젝트는 다음과 같은 실습 주제들로 구성할 수 있습니다. RESTful API는 실제 서비스 개발의 핵심이므로, 단순한 CRUD에서 시작해 점점 더 복잡한 기능을 추가하는 방식으로 학습하면 좋습니다.

1. 기본 CRUD API 개발 실습

목표

  • RESTful API의 기본적인 CRUD 작업을 이해하고 구현합니다.
  • Spring Boot를 사용하여 간단한 데이터 관리 API를 만듭니다.

과제

  1. 요구사항

    • POST /items: 새로운 아이템 생성
    • GET /items: 모든 아이템 조회
    • GET /items/{id}: 특정 아이템 조회
    • PUT /items/{id}: 특정 아이템 수정
    • DELETE /items/{id}: 특정 아이템 삭제

  2. 구현 방법

    • Spring Boot 프로젝트 생성
    • Item 엔티티 클래스 정의 (예: id, name, description)
    • H2 Database와 Spring Data JPA 연동
    • @RestController 및 HTTP 메서드를 사용한 CRUD 엔드포인트 구현

  3. 추가 학습

    • @ResponseEntity를 사용한 응답 처리
    • 예외 처리 (@ControllerAdvice)

2. 페이징, 정렬 및 필터링

목표

  • RESTful API에 페이징, 정렬, 필터링을 구현하여 대량 데이터 처리에 대한 실습을 진행합니다.

과제

  1. 요구사항

    • /items?page=0&size=10: 페이지와 크기를 지정해 데이터 조회
    • /items?sort=name,asc: 이름 기준으로 오름차순 정렬
    • /items?filter=keyword: 특정 키워드를 포함하는 아이템 필터링

  2. 구현 방법

    • Spring Data JPA의 Pageable과 JpaSpecificationExecutor를 사용
    • 요청 파라미터로 페이징, 정렬, 필터링 적용

  3. 추가 학습

    • 페이징 메타데이터 응답 추가 (totalPages, totalElements)
    • 클라이언트 친화적인 API 설계

3. 인증 및 권한 부여 (Authentication & Authorization)

목표

  • RESTful API의 보안을 강화하기 위해 Spring Security를 활용하여 인증 및 권한 부여를 구현합니다.

과제

  1. 요구사항

    • POST /login: 사용자 로그인
    • POST /signup: 사용자 회원가입
    • GET /profile: 로그인한 사용자 정보 조회 (JWT 사용)
    • 역할 기반 권한 부여 (예: ROLE_ADMIN, ROLE_USER)

  2. 구현 방법

    • Spring Security와 JWT(Json Web Token) 연동
    • 사용자 인증 및 역할 기반 인가 구현
    • @PreAuthorize 및 SecurityContextHolder 활용

  3. 추가 학습

    • 비밀번호 암호화 (BCryptPasswordEncoder)
    • Spring Security FilterChain 이해

4. 파일 업로드 및 다운로드

목표

  • RESTful API를 통해 파일 업로드 및 다운로드 기능을 구현합니다.

과제

  1. 요구사항

    • POST /files: 파일 업로드
    • GET /files/{id}: 파일 다운로드
    • GET /files: 업로드된 파일 목록 조회

  2. 구현 방법

    • MultipartFile 사용
    • 파일 저장 (로컬 파일 시스템 또는 데이터베이스)
    • 파일의 메타데이터 관리 (파일 이름, 경로, 크기 등)

  3. 추가 학습

    • AWS S3와 같은 클라우드 스토리지 연동

5. 외부 API 연동

목표

  • RESTful API를 통해 외부 서비스를 통합하거나 데이터를 가져오는 실습을 합니다.

과제

  1. 요구사항

    • GitHub의 REST API를 사용하여 특정 사용자 정보 가져오기
    • /github/users/{username} 엔드포인트 구현
    • 외부 API의 응답 데이터를 클라이언트에 전달

  2. 구현 방법

    • Spring WebClient 또는 RestTemplate 사용
    • 외부 API 호출 및 응답 매핑
    • 에러 처리 (예: API 호출 실패 시)

  3. 추가 학습

    • OAuth 2.0을 사용한 인증된 외부 API 호출

6. 예외 처리 및 글로벌 에러 핸들링

목표

  • API 요청 및 응답 과정에서 발생하는 예외를 관리하고, 사용자 친화적인 에러 메시지를 반환합니다.

과제

  1. 요구사항

    • 클라이언트의 잘못된 요청에 대해 400 상태 코드 반환
    • 서버 내부 오류에 대해 500 상태 코드 반환
    • @ControllerAdvice와 @ExceptionHandler 사용

  2. 구현 방법

    • 커스텀 예외 클래스 생성
    • 글로벌 예외 처리 핸들러 구현
    • 응답 형식 통일 (예: {"error": "message", "status": 400})

  3. 추가 학습

    • Spring Boot의 기본 에러 처리 메커니즘 분석

7. 대규모 데이터를 처리하기 위한 배치 작업 (Batch Processing)

목표

  • 대규모 데이터 처리 및 정기 작업을 RESTful API와 연계하여 학습합니다.

과제

  1. 요구사항

    • 매일 실행되는 데이터 처리 배치 작업 (예: 로그 데이터 정리)
    • /batch/start: 배치 작업 수동 시작
    • 배치 작업의 상태 확인 및 관리

  2. 구현 방법

    • Spring Batch를 사용하여 데이터 처리 로직 작성
    • REST API와 Spring Batch 통합
    • 배치 작업 상태 확인 엔드포인트 구현

  3. 추가 학습

    • 비동기 작업 처리 (@Async)
    • 대규모 데이터를 처리하기 위한 최적화

8. 통합 테스트

목표

  • RESTful API를 실제로 테스트하여 동작과 품질을 검증합니다.

과제

  1. 요구사항

    • CRUD API의 모든 기능에 대해 테스트 작성
    • 예외 상황 및 엣지 케이스 테스트

  2. 구현 방법

    • Spring Boot Test 및 MockMvc 사용
    • 데이터베이스와의 통합 테스트 작성
    • @Transactional 및 H2 Database 활용

  3. 추가 학습

    • REST API 문서화를 위한 RestDocs 사용

9. RESTful API 문서화

목표

  • API 문서를 작성하여 다른 개발자들이 API를 쉽게 사용할 수 있도록 합니다.

과제

  1. 요구사항

    • /items API의 전체 문서화
    • 요청/응답 샘플, 상태 코드 설명 포함

  2. 구현 방법

    • Swagger/OpenAPI 3.0 사용
    • 문서화 자동 생성
    • 문서에 필요한 커스텀 설명 추가

  3. 추가 학습

    • API 버전 관리 및 문서화

10. 간단한 프로젝트 실습

주제 예시

  • To-Do List API:
    • 사용자별로 할 일 관리
    • 상태(완료/미완료) 업데이트
    • 완료된 할 일만 필터링
  • 도서 관리 API:
    • 도서 등록, 수정, 삭제, 검색
    • 특정 카테고리별로 도서 조회
  • 게시판 API:
    • 사용자 인증 및 댓글 기능 포함
    • 게시글 페이징 및 검색

실습 과정에서 얻을 수 있는 것

  • RESTful API 설계 및 구현에 대한 깊은 이해
  • Spring Boot를 사용한 실제 애플리케이션 개발 경험
  • 보안, 성능, 확장성을 고려한 API 설계 능력
  • 팀원과의 협업 또는 API 문서를 통한 의사소통 능력

실습 후에는 GitHub에 프로젝트를 올리고 포트폴리오에 포함시키는 것도 추천합니다. 각 실습의 완성도를 높이면서 실제 프로젝트 환경에서의 경험을 시뮬레이션할 수 있습니다.

profile
김상욱
이전 포스트

HTTP와 HTTPS의 차이점은 무엇인가요?

다음 포스트

DNS가 어떻게 동작하는지 설명해주세요.

0개의 댓글