Google API Design Guide

Google이 권장하고 사용하는 API Design Guide 문서입니다. Project 진행할 때 참고하면 좋을 것 같습니다.

https://cloud.google.com/apis/design/

Google API Design Guide는 네트워크 API를 위한 종합 디자인 가이드이며, 2014년부터 Google 내부에서 사용되었습니다.

google Cloud API 및 기타 Google API를 디자인할 때도 따르고 있는 가이드입니다.

리소스 중심 디자인

API는 종종 인터페이스 및 메소드를 중심으로 디자인이 되는데, 시간이 지나면서 인터페이스와 메소드가 점점 많아지면 개발자가 각 메소드를 따로 배워야 하기 때문에 결국 API가 지나치게 커져 혼동을 초래할 수 있다.

리소스 중심 디자인의 주요 원칙은 소수의 메소드를 사용해 조작할 수 있도록 이름이 지정된 리소스를 정의하는 것이다.

리소스와 메소드는 API의 명사와 동사로 알려져 있다.

• 리소스는 HTTP 프로토콜을 통해 URL에 자연적으로 매핑되고,
• 메소드는 HTTP 메소드인 POST, GET, PUT, PATCH, DELETE 에 자연적으로 매핑된다.

What is a REST API?

REST API는 개별적으로 주소 지정이 가능한 리소스(API의 명사)의 컬렉션으로 모델링된다. 리소스는 리소스 이름으로 참조가 가능하며, 적은 수의 메소드집합(동사 또는 동작[verbs or operations])을 통해 조작된다.

REST Google API에서 사용되는 표준 메소드는

• List, Get, Create, Update, Delete 이다.

• 데이터베이스 트랙잭션과 같이 표준 메소드로 쉽게 매핑되지 않는 기능은 커스텀 메소드(커스텀 동사 또는 커스텀 작업[custom verbs or custom operations])을 사용할 수 있다.

Design flow

리소스 중심 API를 디자인할 때 다음과 같은 단계를 따르도록 권장한다.

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

리소스

리소스 중심 API는 일반적으로 리소스 계층 구조로 모델링된다.이 때 각 노드는 단순 리소스 이거나 컬렉션 리소스 이다. 이러한 노드들은 편의상 각각 리소스 와 컬렉션 으로 불리는 일이 많다.

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

메소드

리소스 중심 API의 주요 특징은 리소스에서 실행되는 메소드(기능)보다 리소스(데이터 모델)를 강조한다는 점이다. 일반적인 리소스 중심 API는 다수의 리소스와 소수의 메소드를 함께 제공한다.

이 때 메소드는 표준 메소드 또는 커스텀 메소드가 될 수 있다.

API의 기능이 표준 메소드(List, Get, Create, Update, Delete) 하나에 자연적으로 매핑되는 경우에는 해당 메소드를 API 디자인에 사용한다.

자연적으로 매핑되지 않은 경우 커스텀 메소드를 사용한다.

Example

Gmail API

• API 서비스 : gmail.googleapis.com
  • 사용자 컬렉션 : users/*
    • 메시지 컬렉션 : users/*/messages/*
    • 스레드 컬렉션 : users/*/threads/*
    • 라벨 컬렉션 : users/*/labels/*
    • 사용자 프로필을 나타내는 리소스 : users/*/profile
    • 사용자 설정을 나타내는 리소스 : users/*/settings

Cloud Pub/Sub API

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

리소스 이름

리소스 중심 API에서 리소스는 이름이 지정된 개체이고,*리소스 이름 *은 식별자 이다. 리소스마다 고유한 리소스 이름이 있어야 한다.

리소스 이름은 리소스 자체의 ID와 상위 리소스의 ID, 그리고 API 서비스 이름으로 구성된다.