REST API의 기본 이해와 사용법

API ?

REST API를 설명하기 전에 API가 무엇인지 살펴보겠습니다.

API(Application Programming Interface)란 구글 맵 API, 카카오 비전 API 등 소프트웨어나 시스템 간의 상호작용을 가능하게 하는 규약 또는 인터페이스입니다.

이를 활용하면 API는 개발자가 복잡한 기능을 직접 구현하지 않고도, 특정 작업을 수행하거나 외부 서비스의 데이터를 접근할 수 있게 해줍니다.

API의 주요 장점은 다음과 같습니다.

재사용성: 이미 개발된 기능을 재사용하여 개발 시간과 비용을 절약할 수 있습니다.
효율성: 복잡한 기능을 쉽고 빠르게 구현할 수 있어 개발 프로세스가 더욱 효율적입니다.
호환성: 다양한 시스템, 언어, 플랫폼 간에 데이터와 기능을 쉽게 공유할 수 있습니다.
보안: API를 통해 데이터와 기능에 대한 접근을 제어하고, 사용자 인증 및 권한 부여를 관리할 수 있습니다.

REST API

REST API는 Representational State Transfer의 약자로, 웹 기반 통신에서 클라이언트와 서버 간에 데이터를 주고받는 방법 중 하나입니다.

REST API라는 것은 REST 원칙을 적용하여 서비스 API를 설계한 것을 말하며 대부분의 서비스가 REST API를 제공합니다.

이 REST API를 이용하면, 웹 상의 다양한 자원(Resource)을 표준 HTTP 메소드를 사용하여 관리할 수 있습니다.

이 자원들은 일반적으로 텍스트, 이미지, 서비스 처리 등 여러 형태가 될 수 있습니다.

즉, RESTful API는 웹의 기본 프로토콜 HTTP를 사용하여 서비스의 리소스에 접근하고, 데이터 교환을 수행합니다.

REST API의 핵심 특징을 요약하고, 다른 API 스타일과 비교하여 표로 정리해 보겠습니다.

특징	REST API 설명	다른 API 스타일과의 비교
클라이언트-서버 구조	클라이언트와 서버가 독립적으로 분리되어 있습니다. 클라이언트는 UI에 초점을 맞추고, 서버는 데이터와 백엔드 로직을 처리합니다.	대부분의 API 스타일에서 공통적인 구조입니다.
무상태(Stateless)	각 요청은 독립적이며, 서버는 클라이언트의 상태 정보를 저장하지 않습니다. 모든 요청에는 필요한 모든 정보가 포함되어야 합니다.	SOAP 등 다른 API 스타일에서는 세션 정보를 유지하기 위해 상태를 저장할 수 있습니다.
캐시 가능(Cacheable)	응답은 캐시가 가능하도록 명시적으로 표시되어야 합니다. 이를 통해 클라이언트는 응답을 재사용할 수 있어 효율성이 향상됩니다.	다른 API 스타일에서도 캐싱은 가능하지만, REST는 캐싱을 기본 원칙으로 삼습니다.
계층화된 시스템	클라이언트는 종단 서버와 직접 통신하지 않아도 되며, 중간 서버를 통해 요청을 전송할 수 있습니다.	다른 API 스타일에서도 계층화는 가능하지만, REST에서는 더 명시적으로 사용됩니다.
일관된 인터페이스	REST API는 자원(Resource)의 표현을 통해 서비스와 상호작용합니다.	URI를 통해 자원을 식별하고, HTTP 메소드(GET, POST 등)를 사용하여 자원에 대한 행위를 정의합니다. SOAP과 같은 다른 스타일은 보통 단일 엔드포인트를 사용하며, 행위는 메시지 안에 명시됩니다.
코드 온 디맨드 (선택적)	서버는 실행 가능한 코드를 클라이언트에 전송할 수 있습니다(예: JavaScript). 이는 선택적 기능입니다.	대부분의 API 스타일에서는 드물게 사용되는 특징입니다.

REST API의 핵심

리소스에 대한 행위는 HTTP의 아래의 Method로 표현해야 합니다.
URI는 자원(리소스)를 표현해야 한다. - 리소스 명은 동사가 아닌 명사를 사용해야 한다.

동작 HTTP	메소드	URI 예시	설명
리소스 조회	GET	/users	모든 사용자의 정보를 조회합니다.
특정 리소스 조회	GET	/users/{userId}	ID에 해당하는 특정 사용자의 정보를 조회합니다.
리소스 생성	POST	/users	새로운 사용자를 생성합니다. 데이터는 요청 본문에 포함됩니다.
리소스 업데이트	PUT	/users/{userId}	ID에 해당하는 특정 사용자의 정보를 업데이트합니다. 데이터는 요청 본문에 포함됩니다.
리소스 부분	업데이트	PATCH /users/{userId}	ID에 해당하는 특정 사용자의 특정 정보만을 업데이트합니다. 데이터는 요청 본문에 포함됩니다.
리소스 삭제	DELETE	/users/{userId}	ID에 해당하는 특정 사용자를 삭제합니다.

예시 - 자바스크립트코드를 통해 사용자 정보 처리

사용자 정보 조회(GET 요청)

fetch.js

fetch('https://example.com/api/users/1', {
  method: 'GET', // HTTP 메소드 지정
  headers: {
    'Accept': 'application/json' // 클라이언트가 받기를 원하는 컨텐츠 타입
  }
})
.then(response => {
  if (response.ok) {
    return response.json(); // 응답을 JSON 형식으로 파싱
  }
  throw new Error('Network response was not ok.');
})
.then(userData => console.log(userData)) // 사용자 데이터 처리
.catch(error => console.error('There has been a problem with your fetch operation:', error));

사용자 정보 생성(POST 요청)

fetch.js

fetch('https://example.com/api/users', {
  method: 'POST', // HTTP 메소드 지정
  headers: {
    'Content-Type': 'application/json', // 요청 본문의 컨텐츠 타입 지정
    'Accept': 'application/json' // 클라이언트가 받기를 원하는 컨텐츠 타입
  },
  body: JSON.stringify({
    name: 'John Doe', // 생성할 사용자의 이름
    email: 'john.doe@example.com' // 생성할 사용자의 이메일
  }) // 요청 본문에 포함될 사용자 데이터
})
.then(response => {
  if (response.ok) {
    return response.json(); // 응답을 JSON 형식으로 파싱
  }
  throw new Error('Network response was not ok.');
})
.then(newUserData => console.log(newUserData)) // 새로 생성된 사용자 데이터 처리
.catch(error => console.error('There has been a problem with your fetch operation:', error));

로이필딩 논문