RESTful API 공부하기

서론

---

RESTful API란 무엇이고 어떻게 사용하는지 간단히 정리하고자 합니다.

 

https://github.com/hosunghyun/Smart_Makeup_Web.git

GitHub - hosunghyun/Smart_Makeup_Web: 웹으로 캠을 사용하여 서버로 화장 시뮬레이션을 제공

 최근 진행 중인 Smart MakeUP 프로젝트에서 Spring Boot를 활용한 서버에서 CRUD를 구현했지만 확실하게 RESTful API란 기술을 공부하고자 합니다.

 

RESTful API란?

RESTful API는 두 컴퓨터 시스템이 인터넷을 통해 정보를 안전하게 교환하기 위해 사용하는 인터페이스입니다.

https://aws.amazon.com/ko/what-is/restful-api/

RESTful API란 무엇인가요? - RESTful API 설명 - AWS

RESTful API는 Representational State Transfer (REST) 아키텍처 스타일을 기반으로 설계된 API를 의미합니다. REST는 네트워크 상에서 클라이언트와 서버 간의 상호작용을 간단하고 확장 가능하며 표준화된 방식으로 정의하기 위한 규칙입니다. RESTful API는 이러한 원칙을 준수하여 설계된 API로, 일반적으로 HTTP 프로토콜을 사용하여 자원(Resource)에 접근하고 조작합니다.

 

즉 클라이언트가 어떤 방식으로 요청을 하면 서버는 어떤 방식으로 응답할 지 지정해 놓은 다영한 형식 중 하나입니다.

 

REST의 기본 원칙

자원이 식별(Resource Identification)

각 자원은 고유한 URI(Uniform Resource Identifier)로 식별됩니다.

 

표현(Representation)

자원은 JSON, XML 등의 포맷으로 클라이언트에 반환됩니다.

 

 

상태 없는 통신(Stateless)

각 요청은 자체적으로 완전하며, 요청 간에 서버에 상태 정보가 유지되지 않습니다.

 

표준 HTTP 메소드 사용

HTTP 메소드를 사용하여 자원에 대한 동작을 정의합니다.

GET, POST, PUT, PATCH, DELETE

 

HTTP 상태 코드 사용

서버는 요청 결과를 나타내기 위해 표준 HTTP 상태 코드를 반환합니다.

• 200 : 성공
• 201 : 자원 생성 성공
• 400 : 잘못된 요청
• 401 : 인증 실패
• 404 : 자원 없음
• 500 : 서버 오류

즉 성공하면 200번대 상태 코드가 응답으로 전달되고 클라이언트의 요청에 문제(잘못된 URI, 권한 외 요청 등)는 400번대 상태 코드가 응답으로 전달됩니다. 500번대는 서버 측의 문제로 오류가 발생했을 경우 반환됩니다.

 

RESTful API 설계의 핵심 요소

RESTful API에서는 자원은 서버에서 관리되는 데이터나 서비스로 URI를 통해서 접근할 수 있습니다.

 

예시

htt://api.example.com/users

 

 

HTTP 메소드에는 여러가지 메소드가 존재하는데 RESTful API에 사용되는 것만 살펴보면 다음과 같습니다.

HTTP 메소드	URI	설명
GET	/users	모든 사용자 조회
GET	/users/1	특정 사용자 조회
POST	/users	사용자 생성
PUT	/users/1	특정 사용자 전체 수정
PATCH	/users/1	특정 사용자 일부 수정
DELETE	/users/1	특정 사용자 삭제

메소드와 URI를 보면 어떤 명령인지 구분하기 힘들 수 있습니다.

 

GET과 DELETE는 우편으로 POST, PUT, PATCH는 소포라고 비유할 수 있습니다. 즉 POST, PUT, PATCH는 GET, DELETE보다 많은 내용을 담을 수 있습니다.

 

택배 회사도 여러개가 존재하듯이 POST, PUT, PATCH와 GET, DELETE는 서로 다른 방식입니다. 즉 특성이나 목적이 다르다는 의미입니다.

 

그래서 각 요청을 어떤 방식으로 전송하는가에 따라서 어떤 작업을 요청하는 것인지 알아낼 수 있습니다.

 

// 요청 예제 (JSON 포맷)
POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john.doe@example.com"
}

// 응답 예제 (JSON 포맷)
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 1,
  "name": "John Doe",
  "email": "john.doe@example.com"
}

RESTful API의 요청과 응답에는 구조화된 데이터 표현이 가능하면서 가벼운 JSON 형식이 많이 사용됩니다.

 

RESTful API의 장점과 단점

장점

1. 확장성 : 독립적인 클라이언트와 서버 구조로 확장성 제공
2. 유연성 : 다양한 데이터 포맷과 플랫폼에서 동작 가능
3. 표준화 : HTTP 프로토콜을 활용한 표준화된 통신

단점

1. 복잡한 요청 : 상태 없는 통신으로 인해 일부 요청이 복잡해질 수 있음
2. 실시간 기능 한계 : WebSocket이나 gRPC와 같은 실시간 통신에 부적합