REST API

Minsu Lee·2023년 6월 5일

REST API

✨SEB FE

Unit8 [HTTP/네트워크]실습

💡 Slow and steady win the race.

📌 REST API

REST (Representational State Transfer) API는 웹 기반의 소프트웨어 아키텍처 스타일 중 하나로, 클라이언트와 서버 간의 통신을 위한 표준화된 방법을 제공하는 인터페이스이다.

REST(Representational State Transfer) API는 웹에서 사용되는 모든 데이터나 자원(Resource)을 HTTP URI로 표현한다.

API는 클라이언트와 서버 사이에도 데이터와 리소스를 요청하고, 요청에 따른 응답을 전달하기 위해 사용된다. 이 API를 보고 클라이언트는 서버에 요구사항을 요청하고, 이에 대한 응답을 서버에서 클라이언트로 전송한다.

HTTP 프로토콜을 기반으로 요청과 응답에 따라 리소스를 주고받기 위해서는 알아보기 쉽고 잘 작성된 API가 필요하다.

🔍 REST API의 구성

구성요소	내용	표현 방법
자원(resource)	자원	URL(엔드포인트)
행위(verb)	자원에 대한 행위	HTTP 요청메소드
표현(representations)	자원에 대한 행위의 구체적 내용	페이로드

🔍 REST API의 성숙도 단계

✨ 0 단계: HTTP 사용 !
단순 HTTP 프로토콜을 사용하는 것 (요청, 응답)
→ 사실상 REST API라고 할 수 없다..

이 단계에서는 REST 원칙을 따르지 않는 기본적인 HTTP 기반 웹 서비스를 제공한다.
XML 기반의 SOAP(Simple Object Access Protocol)과 유사한 방식으로 데이터를 주고받는다.
HTTP 메서드와 상태 코드를 제대로 활용하지 않으며, 리소스 식별에 경로 대신 쿼리 문자열을 사용할 수도 있다.

✨ 1 단계: 개별 리소스와 통신 준수 !
개별 리소스(Resource)와의 통신을 준수해야 한다.
모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야 하며 요청하고 받는 자원에 대한 정보를 응답으로 전달해야한다.

1단계에서는 요청하는 리소스가 무엇인지에 따라 각기 다른 엔드포인트로 구분하여 사용한다.

이 단계에서는 API에 리소스 개념을 도입하여 RESTful한 아키텍처의 기본 원리를 적용한다.
리소스 개념은 클라이언트가 접근하고 조작할 수 있는 추상적인 개체를 나타낸다.
리소스에 고유한 URI를 할당하고, URI를 통해 리소스에 접근하고 조작한다.
여전히 HTTP 메서드와 상태 코드를 제대로 활용하지 않을 수 있다.

💡 엔드포인트 작성 시에는 동사, HTTP 메서드, 혹은 어떤 행위에 대한 단어 사용은 지양하고, 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직한 방법이다.

✨ 2 단계: HTTP 메소드 원칙 준수 !
2단계에서는 CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점 (CRUD(Create, Read, Update, Delete)) HTTP 메서드를 사용할 때 몇 가지 규칙에도 유의해야 한다.

이 단계에서는 HTTP 메서드를 적절하게 활용하여 리소스를 조작한다.
HTTP GET, POST, PUT, DELETE 등의 메서드를 사용하여 리소스의 조회, 생성, 수정, 삭제 작업을 수행한다.
상태 코드를 올바르게 활용하여 작업 결과를 클라이언트에게 반환한다.
Hypermedia(하이퍼미디어) 기능을 도입하여 API에 관련 리소스 간의 탐색을 쉽게 할 수도 있다.

API를 작성할 때, REST 성숙도 모델의 2단계까지 적용하면 대체적으로 잘 작성된 API이다.

✨ 3 단계: HATEOAS 원칙 준수 !
HATEOAS(Hypermedia As The Engine Of Application State)라는 약어로 표현되는 하이퍼미디어 컨트롤을 적용한다. 3단계의 요청은 2단계와 동일하지만, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야 한다.

응답에 들어가게 되는 링크 요소는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있다.

이 단계에서는 하이퍼미디어를 최대한 활용하여 API의 탐색과 상호작용을 촉진한다.
API 응답에 링크와 같은 추가 정보를 포함시켜 클라이언트가 API를 탐색하고 사용할 수 있게 한다.
클라이언트는 링크를 따라가며 새로운 리소스를 발견하고 API와 상호작용한다.
하이퍼미디어 제공을 통해 클라이언트와 서버 간의 느슨한 결합을 달성한다.

🔍 REST API의 설계 원칙

리소스 중심 (Resource-Centric): API는 리소스를 중심으로 설계되어야 한다. 리소스는 클라이언트가 접근하고 조작할 수 있는 추상적인 개체를 나타낸다. 각 리소스는 고유한 식별자(URI)를 가지며, 클라이언트는 URI를 사용하여 리소스에 접근하고 조작한다.

//리소스를 식별할 수 있는 이름은 동사보단 명사를 사용한다.
#Bad
GET /getTodos/1

#Good
GET /todos/1

HTTP 메서드 활용 (HTTP Method Usage): HTTP 메서드는 API의 작업을 수행하는 데 사용된다. 가장 일반적으로 사용되는 메서드는 GET(조회), POST(생성), PUT(수정), DELETE(삭제)다. 각 메서드는 해당하는 작업을 수행하기 위해 정의된 의미를 가지고 있으며, 적절한 메서드를 사용하여 리소스를 조작해야 한다.

//리소스에 대한 행위는 HTTP 요청 메서드를 통해 표현하며 URL에 표현하지 않는다.
#Bad
GET /todos/delete/1

#Good
DELETE /todos/1

🔍 REST API의 특징

리소스 기반: API의 핵심 개념은 리소스이다. 리소스는 웹에서 접근 가능한 개체로써, 데이터 또는 기능을 나타낸다. 각 리소스는 고유한 식별자(URI)를 가지며, 클라이언트는 URI를 사용하여 리소스에 접근하고 조작한다.
HTTP 메서드 활용: REST API는 HTTP의 다양한 메서드를 사용하여 리소스를 조작한다. 가장 일반적으로 사용되는 메서드는 GET(조회), POST(생성), PUT(수정), DELETE(삭제)다. 각 메서드는 해당하는 작업을 수행하기 위해 정의된 의미를 가지고 있다.
상태 없음(Statelessness): REST API는 상태를 관리하지 않는다. 즉, 서버는 각 요청을 개별적으로 처리하고 클라이언트의 상태를 유지하지 않는다. 이는 서버의 확장성과 클라이언트-서버의 느슨한 결합을 가능하게 한다.
자체 서술적 메시지(Self-descriptive messages): REST API는 요청과 응답의 메시지 자체가 어떤 동작을 수행하는지 명확하게 설명할 수 있어야 한다. 이는 메시지에 포함된 헤더와 페이로드를 통해 이루어진다.

🔍 REST API의.. 아주 간단한! 예시

아래 몇가지 REST API 예시..! 너무 추상적인 생각이 들 때! 참고..!!

블로그 게시물 API:
◾ GET /posts: 모든 게시물 가져오기
◾ GET /posts/{id}: 특정 게시물 가져오기
◾ POST /posts: 새로운 게시물 생성
◾ PUT /posts/{id}: 특정 게시물 수정
◾ DELETE /posts/{id}: 특정 게시물 삭제
사용자 관리 API:
◾ GET /users: 모든 사용자 가져오기
◾ GET /users/{id}: 특정 사용자 가져오기
◾ POST /users: 새로운 사용자 생성
◾ PUT /users/{id}: 특정 사용자 수정
◾ DELETE /users/{id}: 특정 사용자 삭제
날씨 정보 API:
◾ GET /weather: 현재 날씨 정보 가져오기
◾ GET /weather/{city}: 특정 도시의 날씨 정보 가져오기