RESTful API를 설명하기 위해선, API REST 에 대한 이해가 먼저 필요하다. REST API 는 결국 REST를 기반으로 한 API이기 때문이다.
1. API
API란 애플리케이션 프로그래밍 인터페이스(API)로써 다른 소프트웨어와 상호 작용하기 위한 규칙과 기능을 제공하는 인터페이스(매개체)이다. 인터페이스라는 단어도 명확히 이해하기가 어려울 수 있다. 웹 또는 앱에서 흔히 보이는 버튼, 검색창, 각종 디자인 요소들을 유저 인터페이스(UI) 라고 한다.
즉, UI는 사람(사용자)과 프로그램 사이의 의사소통에 의해 결과를 시각적으로 보여주는 매개체를 의미하고, API는 프로그램과 또 다른 프로그램을 연결해주는 매개체를 의미한다.
📌 API를 실생활에 비유한다면?
-
메뉴판
API는 레스토랑의 메뉴판과 비슷하다. 메뉴판은 고객이 원하는 음식을 선택할 수 있도록 항목과 설명을 제공한다. 마찬가지로 API는 개발자가 사용할 수 있는 기능과 작업을 나열하고 설명하는 일종의 목록이라 할수 있다. 개발자는 이 메뉴판(API)에서 필요한 기능을 선택하여 사용할 수 있다. -
매뉴얼
제품이나 서비스의 사용 매뉴얼과도 비슷하다. 매뉴얼은 제품이나 서비스를 올바르게 활용하기 위한 지침과 예제를 제공한다. API도 마찬가지로 개발자에게 어떻게 API를 호출하고 데이터를 전송하며 원하는 결과를 얻을 수 있는지에 대한 지침을 제공한다. 사용 매뉴얼은 개발자가 API를 효과적으로 활용할 수 있도록 도와준다.
메뉴판이나 매뉴얼은 사용자에게 제공되는 정보의 종류와 방식에 따라 달라질 수 있는데, API도 다양한 형태로 제공되며, 개발자에게 필요한 정보와 기능을 제공하는 방식이 다를 수 있다.
2. REST
REST(Representational State Transfer)의 약자로 자원을 이름으로 구분하여 해당 자원의 상태를 주고받는 모든 것을 의미하는 아키텍처다. 표현 상태 전송 대표 상태 전송 등으로 번역되곤 한다. 단순히 의미만 보고서는 이해하기 힘드니 주요 개념을 보면서 이해하는 것이 좋을것 같다.
📌 REST의 주요개념
-
자원 (Resources)
시스템에 존재하는 모든 것을 자원으로 간주한다. 예를 들어, 사용자, 제품, 주문 등 모든 개체가 자원이 될 수 있다. -
URI (Uniform Resource Identifier)
자원을 고유하게 식별하는 데 사용되는 URI를 통해 자원에 접근한다. 각 자원은 고유한 URI를 가지며, URI를 통해 자원을 식별하고 참조한다. -
HTTP 메서드
HTTP 프로토콜의 메서드(GET, POST, PUT, DELETE 등)를 사용하여 자원에 대한 작업을 수행한다. 즉 URI에 대해 CRUD를 적용한다. -
상태 전달 (State Transfer)
클라이언트와 서버 간에 상태를 전달하기 위해 데이터를 주고 받는다. 일반적으로 JSON 또는 XML 형식의 데이터가 사용되며, 클라이언트는 서버로 요청을 보내고 서버는 해당 요청에 대한 상태를 응답으로 전달한다.
주요 개념을 포함하여 요약하면, REST란 URI를 통해 자원(Resource)을 이름으로 명시(표현)하고, HTTP Method를 통해 해당 자원에 대한 CRUD를 적용하는 것을 의미한다.
아직 완전히 이해하기 어렵지만 어찌보면 당연하다. REST 아키텍처는 구체적인 구현 방식이나 세부 사항에 대해 명시하지 않기 때문이다. API를 메뉴판에 비유하는 것은 어렵지 않으나 REST 아키텍처를 비유하기엔 다소 어렵기 때문이다.
3. REST API
앞서 API REST 에 대해 설명했던 이유는 결국 오늘의 주제인 REST API를 이해해야 하기 때문이다.
RESPT API란 REST의 원리를 따르는 API를 의미한다. URI를 통해 자원을 이름으로 표현하고, HTTP Method를 통해 해당 자원에 대한 CRUD를 적용하는 API라 할수 있다.
📌 주문 조회 예시
쇼핑몰 사이트에서 주문조회를 할 수있는 REST API를 구현해보자.
-
엔드포인트 (서버에서 자원에 접근할 수 있도록 하는 URL)
/orders/{order_id} -
경로 매개변수 (Path Parameter)
주문 ID(order_id) -
예시 요청
GET /orders/12345 -
예시 응답
{ "order_id": 12345, "item": "책", "quantity": 2, "price": 26000, "status": "주문 완료" }
이런 식으로 REST API는 클라이언트와 서버 간의 통신을 통해 데이터를 주고받고, 서버의 기능을 활용할 수 있게 해준다.
📌 REST API 설계 규칙
- 마지막에 슬래시(/)를 포함하지 않는다.
- 언더바(
_) 대신 대시(-)를 사용한다. - 소문자를 사용한다.
- 파일확장자는 URI에 포함하지 않는다.
- 행위를 포함하지 않는다.
Good
GET /users
POST /products
GET /users/{user_id}/orders
PUT /users/{user_id}
DELETE /users/{user_id}
Bad
GET /Users
POST /add_product
GET /Users/getUserOrders
PUT /updateUser
DELETE /deleteUser/{user_id}
REST API를 설계할 때는 위의 규칙을 따르는 것이 일관성과 가독성을 높이며, 개발자들이 API를 쉽게 이해하고 사용할 수 있도록 도움을 준다.
4. RESTful API
"REST의 원칙을 따르는" , "REST"한 API를 의미하며 RESTful은 REST 아키텍처 스타일을 따르는 웹 서비스나 API를 설계하고 개발하는 방식을 말한다. RESTful은 REST를 REST답게 쓰기 위한 방법으로, 공식적인 용어는 아니며 REST 원리를 따르는 시스템은 RESTful이란 용어로 지칭된다.
