리소스 중심 디자인

본 디자인 가이드의 목적은 개발자가 간단하고, 일관적이고, 사용이 간편한 네트워크 API를 디자인할 수 있도록 지원하는 데 있습니다. 동시에 HTTP 기반 REST API와 소켓 기반 RPC API 디자인을 수렴하는 데도 도움을 줍니다.

RPC API는 종종 인터페이스 및 메서드를 중심으로 디자인됩니다. 시간이 지나면서 인터페이스와 메서드가 점차 많아지면 개발자가 각 메서드를 따로 배워야 하기 때문에 결국 API 표면이 지나치게 커져 혼동을 초래할 수 있습니다. 이는 분명 시간 낭비일 뿐만 아니라 오류가 쉽게 발생하는 원인이 됩니다.

REST의 아키텍처 스타일은 기본적으로 HTTP/1.1을 효과적으로 사용하도록 디자인하기 위해 도입되었지만 이러한 문제를 해결하는 데도 유용합니다. 주요 원칙은 소수의 메서드를 사용해 조작할 수 있도록 이름이 지정된 리소스를 정의하는 것입니다. 리소스와 메서드는 API의 명사와 동사로 알려져 있습니다. 리소스 이름은 HTTP 프로토콜을 통해 자연적으로 URL에 매핑되고 메서드는 자연적으로 HTTP 메서드인 POST, GET, PUT, PATCH, DELETE에 매핑됩니다. 이에 따라 학습해야 할 내용이 크게 줄어들어 개발자는 리소스와 리소스 관계에 집중할 수 있습니다. 단 표준 메서드가 동일하게 적은 수라는 가정을 전제로 합니다.

HTTP REST API는 인터넷에서 큰 성공을 거두었습니다. 2010년에는 공개 네트워크 API의 74%가 HTTP REST(또는 REST와 유사한) API에 해당했으며 대부분 JSON을 통신 형식으로 사용합니다.

HTTP/JSON API가 인터넷에서 널리 사용되고 있지만 처리되는 트래픽 양은 기존 RPC API보다 작습니다. 예를 들어 미국에서 피크 시간에 발생하는 인터넷 트래픽의 약 50%가 동영상 콘텐츠이지만 명백한 성능 문제로 인해 HTTP/JSON API를 사용하여 동영상 콘텐츠를 전송하려는 사람들은 거의 없습니다. 데이터 센터 내부에서는 다수의 기업들이 소켓 기반 RPC API를 사용해 대부분 네트워크 트래픽을 전송합니다. 여기에는 공개 HTTP/JSON API보다 훨씬 많은 양의 데이터(바이트 단위)가 포함될 있습니다.

현실적으로는 RPC API와 HTTP/JSON API 모두 다양한 이유로 인해 필요하지만 이상적으로는 API 플랫폼이 모든 유형의 API에게 최상의 지원을 제공해야 합니다. 이 디자인 가이드는 이러한 원칙을 따르는 API를 디자인하고 빌드하는 데 유용합니다. 이는 일반적인 API 디자인에 리소스 중심 디자인 원칙을 적용하여 이루어지며, 여러 가지 공통 디자인 패턴을 정의하여 유용성을 높이고 복잡성을 줄이기도 합니다.

REST API란 무엇입니까?

REST API는 개별적으로 주소 지정이 가능한 리소스(API의 명사)의 컬렉션으로 모델링됩니다. 리소스는 리소스 이름으로 참조되며 적은 수의 메서드 집합(동사 또는 작업으로도 알려짐)을 통해 조작됩니다.

REST Google API에서 사용되는 표준 메서드(REST 메서드로도 알려짐)는 List, Get, Create, Update, Delete입니다. 데이터베이스 트랜잭션과 같이 표준 메서드로 쉽게 매핑되지 않는 기능은 커스텀 메서드(커스텀 동사 또는 커스텀 작업으로도 알려짐)를 사용할 수도 있습니다.

디자인 흐름

본 디자인 가이드는 리소스 중심 API를 디자인할 때 다음과 같은 단계를 따르도록 권장합니다. 자세한 내용은 아래 각 섹션에서 설명합니다.

API가 제공하는 리소스 유형을 결정합니다.
리소스 사이의 관계를 결정합니다.
유형 및 관계를 기준으로 리소스 이름 스키마를 결정합니다.
리소스 스키마를 결정합니다.
최소한의 메서드 집합을 리소스에 연결합니다.

리소스

리소스 중심 API는 일반적으로 리소스 계층 구조로 모델링됩니다. 이때 각 노드는 단순 리소스이거나 컬렉션 리소스입니다. 이러한 노드를 편의상 종종 각각 리소스와 컬렉션이라 합니다.

컬렉션에는 동일한 유형의 리소스 목록이 포함됩니다. 예를 들어 사용자는 연락처 컬렉션을 갖습니다.
리소스는 상태와 0개 이상의 하위 리소스를 갖습니다. 그리고 각 하위 리소스는 단순 리소스가 되거나, 혹은 컬렉션 리소스가 될 수 있습니다.

예를 들어 Gmail API는 사용자 컬렉션이 있고, 각 사용자는 메시지 컬렉션, 스레드 컬렉션, 라벨 컬렉션, 프로필 리소스, 그리고 여러 설정 리소스가 있습니다.

저장소 시스템과 REST API 사이에는 개념적으로 일치하는 부분이 있지만 리소스 중심 API를 사용하는 서비스가 반드시 데이터베이스일 필요는 없으며 리소스와 메서드를 해석하는 방식에서도 유연성이 매우 큽니다. 예를 들어 캘린더 이벤트(리소스)를 만들 때는 참석자를 위한 추가 이벤트를 만들어 이메일 초대장을 참석자들에게 보낸 다음 회의실을 예약하고 화상회의 일정을 업데이트할 수 있습니다.

메서드

리소스 중심 API의 주요 특징은 리소스에서 실행되는 메서드(기능)보다 리소스(데이터 모델)를 강조한다는 점입니다. 일반적인 리소스 중심 API는 다수의 리소스와 소수의 메서드를 함께 제공합니다. 이때 메서드는 표준 메서드 또는 커스텀 메서드가 될 수 있습니다. 이 가이드의 표준 메서드는List, Get, Create, Update, Delete입니다.

API 기능이 표준 메서드의 하나에 자연적으로 매핑되는 경우에는 해당 메서드를 API 디자인에 사용해야 합니다. 기능이 표준 메서드 중 하나에 자연적으로 매핑되지 않을 경우에는 커스텀 메서드를 사용할 수 있습니다. 커스텀 메서드는 디자인 자유도가 이전 RPC API와 동일하여 데이터베이스 트랜잭션 또는 데이터 분석과 같은 공통 프로그래밍 패턴을 구현하는 데 사용될 수 있습니다.

예시

다음 섹션에서는 리소스 중심 API 디자인을 대규모 서비스에 적용하는 방법에 대해 실제 예를 들어 설명하겠습니다. 추가 예는 Google API 저장소에서 찾아볼 수 있습니다.

이 예시에서 별표는 목록에 포함된 특정 리소스 하나를 나타냅니다.

Gmail API

Gmail API 서비스는 Gmail API를 구현하며 Gmail 기능 대부분을 제공합니다. 리소스 모델은 다음과 같습니다.

API 서비스: gmail.googleapis.com
- 사용자 컬렉션: users/* 각 사용자는 다음과 같은 리소스를 갖습니다.
  - 메시지 컬렉션: users/*/messages/*
  - 스레드 컬렉션: users/*/threads/*
  - 라벨 컬렉션: users/*/labels/*
  - 변경 내역 컬렉션: users/*/history/*
  - 사용자 프로필을 나타내는 리소스: users/*/profile
  - 사용자 설정을 나타내는 리소스: users/*/settings

Cloud Pub/Sub API

pubsub.googleapis.com 서비스는 다음 리소스 모델을 정의하는 Cloud Pub/Sub API를 구현합니다.

API 서비스: pubsub.googleapis.com
- 주제 컬렉션: projects/*/topics/*
- 구독 컬렉션: projects/*/subscriptions/*

Cloud Spanner API

spanner.googleapis.com 서비스는 다음 리소스 모델을 정의하는 Cloud Spanner API를 구현합니다.

API 서비스: spanner.googleapis.com
- 인스턴스 컬렉션: projects/*/instances/* 각 인스턴스에는 다음과 같은 리소스가 있습니다.
- 작업 컬렉션: projects/*/instances/*/operations/*
- 데이터베이스 컬렉션: projects/*/instances/*/databases/* 각 데이터베이스에는 다음과 같은 리소스가 있습니다.
  - 작업 컬렉션: projects/*/instances/*/databases/*/operations/*
  - 세션 컬렉션: projects/*/instances/*/databases/*/sessions/*

소개

리소스 이름