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
- 사용자 컬렉션 : users/*
Cloud Pub/Sub API
- API 서비스 : pubsub.googleapis.com
- 주제 컬렉션 : projects/*/topics/*
- 구독 컬렉션 : projects/*/subscriptions/*
리소스 이름
리소스 중심 API에서 리소스는 이름이 지정된 개체이고,*리소스 이름 *은 식별자 이다. 리소스마다 고유한 리소스 이름이 있어야 한다.
리소스 이름은 리소스 자체의 ID와 상위 리소스의 ID, 그리고 API 서비스 이름으로 구성된다.
'Software Engineering > Software Architecture' 카테고리의 다른 글
Testing Strategies in a Microservice Architecture (0) | 2020.07.13 |
---|---|
[NDC19] 좋은 로그란 무엇인가?: 좋은 로그를 위해 고려해야 할 것들 (0) | 2020.04.13 |
MSA를 진행하면서 고려해야 할 사항들 (0) | 2020.02.11 |
[MSA 개념 정립하기] MSA 아키텍처 패턴 (Client, 운영자, 개발자 측면의 흐름) (1) | 2019.09.09 |