이 문서에서는 Google API와 다양한 HTTP 버전 및 구현이 함께 작동하는 방식을 설명합니다. 생성되었거나 직접 작성된 클라이언트 라이브러리 (대부분 사용 사례에서 권장되는 방식)를 사용하는 경우 이러한 세부정보에 대해 걱정할 필요가 없습니다. 라이브러리는 서버와의 하위 수준 통신을 자동으로 처리합니다.
서드 파티 HTTP 클라이언트를 사용하여 API의 REST 인터페이스에 액세스하는 맞춤 코드를 작성하는 숙련된 개발자라면 여기에 설명된 관련 개념과 선택한 HTTP 라이브러리에서 제공하는 기능을 이해해야 합니다.
통신 프로토콜 사용(HTTP/*)
이 섹션에서는 Google API가 클라이언트와 서버 간 통신에 사용할 수 있도록 지원되는 통신 프로토콜 (일반적으로 HTTP 버전)과 지원되는 통신 프로토콜 사용 시 권장하는 방식을 설명합니다.
HTTP 시맨틱스
API 클라이언트 코드를 개발할 때는 표준 HTTP 프로토콜 시맨틱스를 따릅니다. 서버 측 프록시 또는 API 스택은 표준 HTTP 기능의 하위 집합만 지원하거나, 혹은 하위 호환이 가능한 버전까지 지원할 수도 있습니다.
API의 서버 측 구현체에서 처리해야 하는 HTTP 프로토콜 시맨틱스는 서버 스택에서 제어됩니다. 이러한 기능이 캐싱 지원처럼 API 사양에 명시적으로 포함되어 있는 경우에는 HTTP 프로토콜 시맨틱스만 사용하세요.
HTTP 버전
클라이언트는 클라이언트 플랫폼 또는 클라이언트 측 네트워크에서 허용되거나 서버 측 프록시와의 협상에 따라 모든 HTTP/* 프로토콜을 사용할 수 있습니다. 지원되는 프로토콜에는 HTTP/1.1, HTTP/2, HTTP/3 (QUIC)이 있습니다. HTTP/1.0의 기존 지원은 권장되지 않습니다.
일부 API 기능은 최신 HTTP 프로토콜 버전에서만 지원될 수 있고, 전이중 멀티플렉스 스트리밍과 같은 일부 기능은 HTTP/2 및 HTTP/3에서만 완전하게 지정될 수 있습니다. API 사양에 이러한 기능이 필요한 경우 HTTP 버전에 따라 사용이 제한된다는 점을 알고 있어야 합니다. HTTP/2 서버 푸시와 같은 이전 기능은 지원 중단되었으며 최신 웹 클라이언트에서 지원되지 않습니다.
일반적으로 성능 향상, HOL 차단 감소, 네트워크 오류에 대한 복원력 향상을 위해 HTTP/3 또는 HTTP/2를 사용하는 것이 좋습니다.
채널
채널은 일반적으로 HTTP/1.1 및 HTTP/2의 경우 TCP 소켓, HTTP/3 (QUIC)의 경우 UDP 소켓인 Layer 4 네트워크 연결을 말합니다. 연결은 거의 항상 서버 프로세스를 대신하여 Google 프런트엔드(GFE) 프록시에 의해 종료되므로 클라이언트 애플리케이션은 채널이 엔드 투 엔드로 관리되는 방식에 대해 가정해서는 안 됩니다.
HTTP/1.1 클라이언트: HTTP/1.1을 사용하는 경우 항상 TCP 연결(연결: 연결 유지)을 재사용합니다. HTTP 클라이언트 라이브러리는 일반적으로 재사용을 용이하게 하기 위해 연결 풀을 관리합니다. HTTP/1.1 연결에서 HTTP 파이프라인을 사용하지 마세요. 지원이 제대로 되지 않아 문제가 발생할 수 있습니다. 자세한 내용은 HTTP 및 TCP를 참고하세요.
HTTP/2 및 HTTP/3 클라이언트: 최신 클라이언트와 브라우저는 주로 HTTP/2 또는 HTTP/3을 사용합니다. 두 프로토콜 모두 멀티플렉싱을 지원하므로 단일 연결을 통해 여러 요청과 응답이 동시에 진행될 수 있습니다.
- HTTP/2: 원본당 단일 TCP 연결을 사용합니다.
- HTTP/3: 출처당 UDP를 통해 단일 QUIC 연결을 사용합니다. QUIC는 TLS 암호화, 정체 제어, 연결 관리를 통합하여 연결 설정 속도 (0-RTT 또는 1-RTT) 및 스트림 간 TCP HOL 차단에 대한 내성과 같은 이점을 제공하는 경우가 많습니다.
HTTP/2 및 HTTP/3에서는 단일 호스트에 대한 병렬 TCP 연결 수에 대한 브라우저 제한 (예: 2~10)이 더 이상 주요 성능 문제가 아닙니다. 하지만 서버 (또는 GFE와 같은 프록시)는 단일 HTTP/2 또는 HTTP/3 연결 내에서 동시 스트림의 최대 수를 제한할 수 있습니다. 이렇게 하면 과부하를 방지하고 공정한 리소스 사용을 보장할 수 있습니다 (예: 연결당 동시 요청 또는 스트림을 100개로 제한).
HTTPS
클라이언트는 API 사양에서 지원하는 HTTPS 또는 HTTP를 사용하여 API에 액세스할 수 있습니다. TLS 협상 및 TLS 버전은 클라이언트 애플리케이션에 투명합니다. Google API는 기본적으로 HTTPS 트래픽만 허용합니다.
요청 및 응답 형식
이 섹션에서는 URL 인코딩 데이터 사용, RESTful 작업을 위한 특정 HTTP 메서드, JSON 기반 페이로드 형식을 비롯한 API 상호작용 구조를 설명합니다.
요청 URL
JSON-REST 매핑은 URL로 인코딩된 요청 데이터를 지원하며 HTTP 요청과 응답 본문은 application/json을 Content-Type으로 사용합니다.
HTTP 본문은 JSON 배열을 사용하여 스트리밍되는 RPC 메서드를 지원하며, JSON 배열에는 다수의 JSON 메시지 또는 오류 상태 JSON 메시지가 포함될 수 있습니다.
긴 요청 URL
URL에는 실제 길이 제한이 있으며, 일반적으로 기본적으로 16KB로 설정되지만 서버에 따라 다를 수 있습니다. API가 이 길이를 초과하는 URL과 함께 GET 요청을 사용하면 요청이 대상 API 서버에 도달하지 못하고 Google 프런트엔드 (GFE)에서 Your client has issued a malformed or illegal request. 오류 메시지와 함께 거부됩니다.
이러한 제한을 우회하려면 클라이언트 코드는 HTTP 헤더 X-HTTP-Method-Override: GET과 함께 Content-Type을 application/x-www-form-urlencoded로 하여 POST 요청을 사용해야 합니다. 이 방법은 DELETE 요청에도 사용할 수 있습니다.
HTTP 메서드 (동사)
요청 URL이 REST 모델을 따르는 경우에는 HTTP 메소드가 API 사양의 일부로 지정됩니다. 특히 모든 API 메서드는 API 메서드가 매핑되는 특정 HTTP 동사에 따라 HTTP 프로토콜의 요구사항을 준수해야 합니다 자세한 내용은 HTTP(Hypertext Transfer Protocol) 사양과 PATCH 메서드 RFC를 참고하세요.
HTTP GET 및 HEAD와 같은 안전한 메서드는 가져오기 외에 다른 작업을 표현해서는 안 됩니다. 특히 HTTP GET은 안전한 메서드로 간주되어야 하며 클라이언트에서 나타나는 부작용이 있어서는 안 됩니다.
HTTP의 멱등성은 다수의 동일한 요청에서 발생하는 부작용이 단일 요청에서 발생하는 부작용과 동일하다는 것을 의미합니다. GET, PUT, DELETE는 스타일 가이드와 관련된 멱등성을 갖는 HTTP 메서드입니다. 단, 멱등성은 오직 서버 부작용과 관련하여 표현되며, 응답에 대해서는 어떤 것도 지정하지 않습니다. 특히 존재하지 않는 리소스의 DELETE는 404 (Not Found)를 반환해야 합니다.
HTTP POST 및 PATCH는 안전한 메소드도 아니고 멱등성을 갖지도 않습니다. PATCH는 RFC 5789에서 도입되었습니다.
| HTTP 동사 | 안전 | 멱등성 |
|---|---|---|