RESTful API 📶

REST API는 HTTP 요청을 사용하여 데이터에 액세스하고 사용하는 API (응용 프로그램 인터페이스)의 아키텍처 스타일이라고 정의된다. 해당 한 문장으로는 당최 이해하기 힘들기 때문에 이를 간단히 해석해보자.

우선 REST는 "REpresentational State Transfer"의 약자로 HTTP URI를 통해 자원을 명시하고, HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미한다. 간단히 말해 모든 자원에 고유한 URI를 부여하고 활용하는 방법론을 의미한다. REST의 구성 요소는 다음과 같다.

• URI(Uniform Resource Identifier): 해당 사이트의 특정 자원의 위치를 나타내는 유일한 주소
• HTTP Method: HTTP request가 의도하는 action을 정의한 것
• Payload: HTTP request에서 server로 보내는 데이터(body)

이러한 REST 특징에 기반하여 API를 구현한 것이 REST API라고 하며, 이를 이해하기 쉽고 사용하기 쉽도록 만드는 것이 RESTful API라고 정의할 수 있을 것 같다.

REST API의 장단점 💁‍♂️

REST API의 다양한 특징 중 대표적인 장점은 Self-descriptiveness(자체 표현 구조)를 갖는다는 것이다. 이는 REST API 메시지만으로도 이를 이해하기 쉬운 구조를 갖고 있다는 것이다. 다음의 예시를 통해 이를 알아보자.

HTTP POST , http://localhost:8080/board

{

  "board": {

  "title":"제목",

  "content":"내용"

  }

}

위 메시지를 확인해보면, http://localhost:8080/board 라는 주소로 board 라는 데이터에 title 과 content 라는 것을 포함하여 추가(POST)하는 요청 임을 알 수 있다.

이에 반해 단점으로 표준이 존재하지 않기에 안티 패턴이 존재할 수 있다는 점을 꼽을 수 있다. 즉, 명확한 표준 규약이 존재하지 않기에 실제로 많이 쓰이지만 비효율적이거나 비생산적인 패턴이 존재할 수 있다는 것이다.

REST API 설계 규칙 📋

REST API를 설계할 때, 다음과 같은 규칙을 고려할 수 있다.

1. URI는 정보의 자원을 명확히 표현해야 한다. 그렇기에 동사가 아닌 명사로 표현하며, 대문자보다 소문자를 사용한다. 또한 리소스의 원형마다 단/복수 단위를 구분하여 사용한다.
   Ex) GET /Users/1

2. 자원에 대한 행위는 HTTP Method를 통해 표현하고, URI에는 HTTP Method를 포함하지 않는다.
   Ex) GET delete/Users/1 ➡️ DELETE /Users/1
   Ex) GET /Users/show/1 ➡️ GET /Users/1

3. 리소스 간에는 연관 관계가 있는 경우, /리소스명/리소스 ID/관계가 있는 다른 리소스명. 아래 예시의 중괄호는 변수를 의미
   Ex) GET /Users/{user_id}/profile

4. 슬래시(/)를 통해 계층 관계를 나타낸다.

5. 파일의 경우 확장자명을 URI에 포함하지 않는다.
   Ex) GET /Users/1/photo.jpeg ➡️ GET /Users/1/photo

6. URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
   Ex) GET /Users/profile/ 🚫

7. 길어지는 URI의 가독성을 위해서 하이픈(-)을 사용하고 언더바(_)는 사용하지 않는다.
   언더바는 보기 어렵거나 밑줄로 인해 가려지는 경우가 있음

RESTful 한 API ❔

위에서 언급한 바와 같이 RESTful 하다는 것은 이해하기 쉽고 사용하기 쉬운 REST API를 만다는 것이다. 이는 근본적인 성능 향상의 측면보다는 일관적인 컨벤션을 통한 개발자들의 이해 및 호환성을 높이는 것이 주 목표이며, 공식적으로 발표된 사항이 아니니 이에 대한 명확한 정의는 없다.

우리는 CRUD라는 기능을 위해 HTTP Method를 사용하고, 이에 따라 각 기능에 적절한 메서드를 다음과 같이 사용할 수 있을 것이다.

위 목적들을 하나의 HTTP Method인 POST로 처리할 수도 있는데, 이러한 경우에 같은 POST 메서드라 직관적으로 이해하기에는 어려움이 있을 수 있기에 RESTful 하지 못한 경우라고 말할 수 있다.

🔖 출처

stampid님 velog : REST API와 RESTful API
망나니 개발자 : [Server] Restful API란?
Heee's Development Blog : [Network] REST란? REST API란? RESTful이란?