구글은 API 어떻게 설계했는지 참고하기 위해서 분석해봤다.
잘 모르면 유명 회사 사례를 따라하는 게 안전하고 쉬우니까.
Youtube DATA API 예
(출처: developers.google.com/youtube/v3/docs)
YouTube DATA API 설명
YouTube Data API를 사용하면 YouTube 웹사이트에서 일반적으로 실행하는 기능을 사용자의 웹사이트 또는 애플리케이션에 통합할 수 있습니다. 아래 목록에서는 API를 사용하여 검색할 수 있는 다양한 유형의 리소스를 확인합니다. API는 이러한 여러 개의 리소스를 삽입하거나 업데이트 또는 삭제하는 메소드도 지원합니다.
참조 가이드에서는 API로 이러한 모든 작업을 수행하는 방법을 설명합니다. 이 가이드는 리소스 유형별로 정리되어 있습니다. 리소스란 동영상, 재생 목록 또는 구독과 같이 YouTube 환경을 구성하는 항목 유형을 의미합니다. 가이드에는 리소스 유형별로 하나 이상의 데이터 표현이 나와 있으며 리소스는 JSON 개체로 표시됩니다. 또한 리소스 유형별로 지원되는 하나 이상의 메소드(LIST, POST, DELETE 등)와 함께 애플리케이션에서 이러한 메소드를 사용하는 방법에 대해 설명합니다.
(출처: https://developers.google.com/youtube/v3/docs)
BASE URL
https://www.googleapis.com/youtube/v3/
기본 URL이다.
v3 API 버전을 가장 먼저 표시한다.
v1, v2, v3이 되었다.
(출처: developers.google.com/youtube/v3/docs/search)
GET Search
https://www.googleapis.com/youtube/v3/search
(출처: developers.google.com/youtube/v3/docs/videos)
GET Videos
https://www.googleapis.com/youtube/v3/videos
(출처: developers.google.com/youtube/v3/docs/channels)
GET Channels
https://www.googleapis.com/youtube/v3/channels
API url이 대부분 videos, playlists, channels 등 리소스resource명, 명사로 되어 있다.
복수형 s를 붙여서 표현했다. 소문자로만 표기했다.
예를 들면 videos의 경우 실제 요청을 해서 여러 video 정보를 받을 수 있다.
무조건 복수형을 사용한 건 아니다.
아래 경우처럼 인증의 경우 youtubepartner 다. 복수형 youtubepartners가 아니라.
인증은 여러 명 한꺼번에 받는 경우가 없기 때문으로 보인다.
리소스별 메소드
각 리소스별로 메소드가 있다.
예 Videos 리소스
(출처: developers.google.com/youtube/v3/docs/videos)
getRating
GET https://www.googleapis.com/youtube/v3/videos/getRating
list
GET https://www.googleapis.com/youtube/v3/videos
insert
POST https://www.googleapis.com/youtube/v3/videos
update
PUT https://www.googleapis.com/youtube/v3/videos
delete
DELETE https://www.googleapis.com/youtube/v3/videos
rate
POST https://www.googleapis.com/youtube/v3/videos/rate
REST 원리에 따라 list, insert, update, delete 모두 같은 url
https://www.googleapis.com/youtube/v3/videos을 사용하고, HTTP 요청 메소드로 구분하게 되어 있다.
list는 GET, insert는 POST, update는 PUT, delete는 DELETE로 HTTP 요청한다.
(참고할 글: 웹 API 디자인)
메소드 표기법은 getRating에서 알 수 있듯이 낙타 소문자 표기법으로 하고 있다.
당연하게 동사 get이 먼저오고 명사 Rating이 나중에 온다.
매개변수명
출처: developers.google.com/youtube/v3/docs/videos/list
예) videos list 의 매개변수
part, chart, id, myRating, maxResults, onBehalfOfContentOwner, pageToken, regionCode, videoCategoryId
대부분 매개변수는 명사다. 당연하다고 볼 수도 있겠지만.
표기법은 낙타 소문자 표기법이다.
페이지처리 방식
데이터를 보내줄 때 다량의 데이터를 모두 한꺼번에 보낼 수 없다. 따라서 데이터를 나눠서 보내주게 된다. youtube api는 pageToken, nextPageToken, prevPageToken을 매개변수로 받아서 페이지별로 보내주는 식이다.
아무래도 youtube의 데이터베이스에서는 새로운 데이터가 끊임없이 입력되므로 저런 token 방식을 쓰는 거 같다.
실제 구현한다면 페이지처리를 어떻게 구현할지는 고민이 필요할 거 같다.
데이터베이스에 새로운 데이터가 실시간으로 다량으로 입력되지 않는다면,
offset 출발점, limit 개수
start 시작점, count 개수 이런 식으로 해도 상관 없을 거 같다.
(참고: REST API 이해와 설계 - #2 API 설계 가이드)
응답 방식: JSON
(출처: developers.google.com/youtube/v3/docs/videos/list)
응답은 JSON으로 한다.
리소스의 속성값(properties)을 응답으로 보내주는 거니, 대부분 명사다. 표기법은 역시 소문자 낙타 방식이다.
id, thumnails, categoryId 등
정리
기본적으로 낙타 소문자 표기법 사용
1. API를 서비스별로 구분
도메인/서비스명
예) google.api.com/youtube
2. API를 버전별로 구분
도메인.com/서비스명/v버전
예) google.api.com/youtube/v3
3. API를 리소스별로 구분
여러개 리소스를 처리할 수 있을 경우 복수형 표기.
리소스명, 명사로 표기
예) google.api.com/youtube/v3/videos
4. API 리소스별 메소드는 REST 방식으로 처리
얻는 것은 GET,
입력은 POST,
수정은 PUT,
삭제는 DELETE
예) list는 GET, insert는 POST, update는 PUT, delete는 DELETE
REST 방식으로 할 수 없는 것은 별도로 처리.
메소드명이므로 동사+명사 형태 예) getRating
5. API 리소스별 메소드별 매개변수
매개변수는 명사. 보통 단수. 예) id: 특정 id 값의 video 정보를 얻을 때