[Network] REST API의 구성 및 특징

Network

[Network] REST API의 구성 및 특징

하부루 2024. 6. 21. 00:04

1. REST API 란?

REST : 자원을 이름으로 구분해 해당 자원의 상태(정보)를 주고 받는 것을 의미한다.

API : 애플리케이션 간의 상호작용을 가능하게 하는 인터페이스를 의미한다. 인터페이스란 어떠한 장치끼리의 정보를 교환하기 위한 수단이나 방법을 의미한다. API는 다양한 형태로 존재하며, 그 목적은 서로 다른 소프트웨어 시스템이 데이터를 교환하고 기능을 공유할 수 있도록 돕는 것에 있다.

REST API : REST의 특징을 기반으로 서비스 API를 구현한 것을 의미한다. 즉 HTTP URI를 통해 자원(Resource)을 명시하고, HTTP Method(POST, GET, PUT, PATCH, DELETE)를 통해 자원에 대한 행위를 표현한다. 각 요청이 어떤 동작이나 정보를 위한 것인지를 그 요청의 모습 자체로 추론이 가능 한 것

RESTful API : REST의 설계 규칙을 잘 지켜서 설계된 API를 말한다.

2. REST API의 구성 요소

자원(Resource) - URI
- HTTP URI는 자원을 식별하기 위한 문자열의 구성
- ex) https://orangenode.com/user/login (’ / ‘) 는 계층 관계를 의미한다.
행위(Verb) - Method
- 행위란 HTTP 메서드를 통해 해당 자원에 CRUD 연산을 적용하는 것을 의미한다.
- GET, POST, PUT, PATCH, DELETE 메소드를 제공Method 역할
  
  GET 데이터 조회
  
  POST 데이터 생성
  
  PUT 데이터 수정(전체 수정)
  
  PATCH 데이터 수정(부분 수정)
  
  DELETE 데이터 삭제
표현(Representations)
- Client와 Server가 데이터를 주고받는 형태로 JSON, XML, TEXT, RSS 등이 있다.

3. REST API의 특징

Client-Server (클라이언트 서버 구조)
- 클라이언트와 서버를 분리하여 서로 의존성이 없는 관계를 가진다.
- 클라이언트는 요청을 담당하고, 서버는 데이터 저장, 처리 및 비즈니스 로직을 관리한다.
- 장점으로는 역할을 명확하게 분리함으로서 개발, 유지보수 및 확장성을 향상시킨다.
Statelessness (무상태성)
- 클라이언트의 데이터를 서버에 저장하지 않는다.
- 세션 정보나 쿠키 정보를 별도로 저장하고 관리하지 않기때문에 API 서버는 단순 요청만 처리한다.
- 장점으로는 서비스의 자유도가 높아지고 구현이 단순해진다.
Cacheable (캐시 가능)
- 웹 표준 HTTP 프로토콜을 그대로 사용하기에 웹에서 사용하는 기존 인프라 활용이 가능하다
- 따라서 HTTP가 가진 강력한 특징 중 하나인 캐싱 기능을 적용할 수 있다.
- 장점으로는 대량의 데이터 요청을 빠르고 효율적으로 처리할 수 있다.
Uniform Interface (인터페이스 일관성)
- URI로 지정한 Resource에 대한 조작을 통일되고 한정적인 인터페이스로 수행한다.
- 특정 언어나 기술에 종속되지 않는다.
Layered System (계층 구조)
- REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층 등을 추가하여 구조를 변경할 수 있다.
- 클라이언트는 서버와 직접 통신하는지, 중간 서버와 통신하는지 알 수 없다.
Self-descriptiveness (자체 표현 구조)
- 요청 메시지만 보고 이를 쉽게 이해 할 수 있는 구조로 되어있다.

4. REST의 장단점

장점

쉬운 사용 HTTP 프로토콜 인프라를 그대로 사용하므로 별도의 인프라를 구축할 필요가 없다.
클라이언트-서버 역할의 명확한 분리 클라이언트는 REST API를 통해 서버와 정보를 주고받는다. REST의 특징인 Stateless에 따라 서버는 클라이언트의 Context를 유지할 필요가 없다.
특정 데이터 표현을 사용 가능 HTTP 프로토콜을 사용하면 헤더 부분에 URI 처리 메소드를 명시하고 필요한 실제 데이터를 ‘body’에 표현할 수 있다. JSON, XML 등 원하는 format으로 사용 가능하다.

단점

표준이 자체가 존재하지 않아 정의가 필요하다.
메소드의 한계 REST는 HTTP 메소드를 이용하여 URI를 표현합니다. 이러한 표현은 쉬운 사용이 가능하다는 장점이 있지만 반대로 메소드 형태가 제한적인 단점이 있다.
구형 브라우저가 아직 제대로 지원해주지 못하는 부분이 존재한다. (PUT, DELETE를 사용하지 못하는 점)

5. REST API 설계 시 중요 사항

URI는 정보의 자원을 표현해야 한다.

* GET /members/update/3 (X) 

URI는 자원을 표현하는데에 집중해야 한다. update와 같은 행위에 대한 표현이 들어가서는 안된다.

자원에 대한 행위는 HTTP Method(GET, POST, PUT, PATCH, DELETE)로 표현한다.

* PATCH /members/3 (O)

회원 수정을 하겠다는 표현을 Method를 통해서 표현한다.

6. REST API 설계 규칙

URI는 명사를 사용한다.

GET /getUserById/:id   (x)             GET /users/:id    (O)

POST /createNewUser    (x)             POST /users       (O)

PATCH /updateUser/:id  (x)             PATCH /users/:id  (O)

DELETE /deleteUser/:id (x)             DELETE /users/:id (O)

자원의 계층 관계를 슬래시( / )로 나타낸다.

<http://localhost:3000/orangenode/memeber/list>

URI 마지막 문자로 슬래시( / )를 포함하지 않는다.

POST /users/ (X)

POST /users  (O)

URI를 쉽게 읽기위해 밑줄( _ )을 사용하지 않고 하이픈( - )을 사용한다.

<https://www.naver.com/members_list> (X)

<https://www.naver.com/members-list> (O)

URI 경로에는 소문자를 사용한다.

<https://www.orangenode.com/order-List> (X)

<https://www.orangenode.com/order-list> (O)

HTTP 응답 상태 코드 사용
파일 확장자는 URI에 포함시키지 않는다.

<http://localhost:3000/orangenode/memeber/list/photo.jpg> (X)

7. @RequestParam vs @PathVariable

@PathVariable
- URL의 일부로 자원을 직접 식별하는 데 사용된다. 경로 변수는 주로 리소스의 고유 식별자(ID)를 지정하는 데 사용된다.
- /users/{userId} 여기서 {userId}는 특정 사용자의 고유 식별자(ID)를 나타내는 경로 변수이다.
- 리소스에 대한 접근이나 특정 리소스의 세부 사항을 요청하는 데 적합합니다.
@RequestParam
- URL의 끝에 ? 뒤에 키-값 쌍으로 추가되는 선택적인 파라미터이다.. 주로 검색, 필터링, 정렬 등의 목적으로 사용됩니다.
- /users?name=Haburu여기서 name=Haburu는 요청 매개변수를 사용하여 name이 Haburu인 사용자를 찾는다.
- 선택적인 쿼리, 필터, 페이지네이션, 정렬 조건과 같이, 리소스 집합에서 특정 데이터를 검색하거나 조회 조건을 제공할 때 사용합니다.

티스토리