Dokumen ini menjelaskan cara Google API berfungsi dengan berbagai versi dan implementasi HTTP. Jika Anda menggunakan library klien buatan kami atau yang dibuat secara manual (pendekatan yang direkomendasikan untuk sebagian besar kasus penggunaan), Anda tidak perlu khawatir tentang detail ini. Library secara otomatis menangani komunikasi tingkat rendah dengan server untuk Anda.
Jika Anda adalah developer berpengalaman yang menulis kode kustom untuk mengakses antarmuka REST API menggunakan klien HTTP pihak ketiga, Anda harus memahami konsep relevan yang didokumentasikan di sini, beserta fitur yang disediakan oleh library HTTP yang Anda pilih.
Menggunakan protokol kabel (HTTP/*)
Bagian ini menjelaskan protokol kabel yang didukung (biasanya versi HTTP) yang dapat digunakan Google API untuk berkomunikasi antara klien dan server, serta cara kami merekomendasikan penggunaannya.
Semantik HTTP
Saat mengembangkan kode klien API, ikuti semantik protokol HTTP standar. Proxy sisi server atau tumpukan API mungkin hanya mendukung subset fitur HTTP standar, dan mungkin juga mendukung versi yang kompatibel dengan versi sebelumnya.
Semantik protokol HTTP yang perlu ditangani oleh implementasi sisi server API dikontrol oleh tumpukan server. Hanya andalkan semantik tersebut jika fitur ini didokumentasikan secara eksplisit sebagai bagian dari spesifikasi API, seperti dukungan caching.
Versi HTTP
Klien dapat menggunakan protokol HTTP/* apa pun, seperti yang diizinkan oleh platform klien atau jaringan sisi klien, atau seperti yang dinegosiasikan dengan proxy sisi server. Protokol yang didukung mencakup HTTP/1.1, HTTP/2, dan HTTP/3 (QUIC). Dukungan lama untuk HTTP/1.0 sangat tidak disarankan.
Beberapa fitur API mungkin hanya didukung oleh versi protokol HTTP yang lebih baru; beberapa hanya sepenuhnya ditentukan dengan HTTP/2 dan HTTP/3, seperti streaming multipleks full-duplex. Perhatikan batasan berbagai versi HTTP jika Anda memerlukan salah satu fitur ini sebagai bagian dari spesifikasi API. Perhatikan bahwa fitur lama seperti HTTP/2 Server Push tidak digunakan lagi dan tidak didukung oleh klien web modern.
Secara umum, kami merekomendasikan HTTP/3 atau HTTP/2 untuk performa yang lebih baik, pengurangan pemblokiran head-of-line, dan ketahanan yang lebih besar terhadap kegagalan jaringan.
Saluran
Saluran mengacu pada koneksi jaringan Lapisan 4, yang biasanya merupakan soket TCP untuk HTTP/1.1 dan HTTP/2, serta soket UDP untuk HTTP/3 (QUIC). Aplikasi klien tidak boleh membuat asumsi tentang cara saluran dikelola secara menyeluruh, karena koneksi hampir selalu dihentikan oleh proxy Google Front End (GFE) atas nama proses server.
Klien HTTP/1.1: Jika menggunakan HTTP/1.1, selalu gunakan kembali koneksi TCP (Connection: Keep-Alive). Library klien HTTP biasanya mengelola kumpulan koneksi untuk memfasilitasi penggunaan kembali. Hindari pipelining HTTP pada koneksi HTTP/1.1; fitur ini tidak didukung dengan baik dan dapat menyebabkan masalah. Untuk mengetahui informasi selengkapnya, lihat HTTP dan TCP.
Klien HTTP/2 dan HTTP/3: Klien dan browser modern sebagian besar menggunakan HTTP/2 atau HTTP/3. Kedua protokol mendukung multipleksing, yang memungkinkan beberapa permintaan dan respons dikirim secara bersamaan melalui satu koneksi.
- HTTP/2—menggunakan satu koneksi TCP per asal.
- HTTP/3—menggunakan satu koneksi QUIC melalui UDP per asal. QUIC mengintegrasikan enkripsi TLS, kontrol kemacetan, dan pengelolaan koneksi, yang sering kali memberikan manfaat seperti penyiapan koneksi yang lebih cepat (0-RTT atau 1-RTT) dan kekebalan terhadap pemblokiran head-of-line TCP di seluruh aliran.
Dengan HTTP/2 dan HTTP/3, batasan browser pada jumlah koneksi TCP paralel ke satu host (misalnya, 2-10) tidak lagi menjadi masalah performa utama. Namun, perlu diketahui bahwa server (atau proxy seperti GFE) masih dapat menerapkan batasan pada jumlah maksimum aliran serentak dalam satu koneksi HTTP/2 atau HTTP/3. Hal ini mencegah kelebihan beban dan memastikan penggunaan resource yang wajar (misalnya, dengan membatasi permintaan atau aliran serentak per koneksi hingga 100).
HTTPS
Klien dapat mengakses API menggunakan HTTPS atau HTTP, seperti yang didukung oleh spesifikasi API. Negosiasi TLS dan versi TLS bersifat transparan untuk aplikasi klien. Secara default, Google API hanya menerima traffic HTTPS.
Format permintaan dan respons
Bagian ini menjelaskan struktur interaksi API, termasuk penggunaan data yang dienkode URL, metode HTTP tertentu untuk tindakan RESTful, dan format payload berbasis JSON.
URL permintaan
Pemetaan JSON-REST mendukung data permintaan yang dienkode URL, dan isi permintaan dan respons HTTP menggunakan application/json sebagai Content-Type.
Isi HTTP menggunakan array JSON untuk mendukung metode RPC yang di-streaming, dan array JSON mungkin berisi sejumlah pesan JSON atau pesan JSON status error.
URL permintaan panjang
URL memiliki batasan panjang praktis, yang biasanya ditetapkan ke 16 KB secara default, meskipun hal ini dapat bervariasi bergantung pada server. Jika API Anda menggunakan permintaan GET dengan URL yang melebihi panjang ini, permintaan mungkin tidak mencapai server API tujuan dan akan ditolak oleh Google Front End (GFE) dengan pesan error Your client has issued a malformed or illegal request.
Untuk melewati batasan ini, kode klien harus menggunakan permintaan POST dengan Content-Type application/x-www-form-urlencoded bersama dengan header HTTP X-HTTP-Method-Override: GET. Pendekatan ini juga berfungsi untuk permintaan DELETE.
Metode HTTP (kata kerja)
Jika URL permintaan mengikuti model REST, metode HTTP-nya akan ditentukan sebagai bagian dari spesifikasi API. Secara khusus, setiap metode API harus mematuhi persyaratan protokol HTTP berdasarkan kata kerja HTTP tertentu yang dipetakan ke metode API. Untuk mengetahui informasi selengkapnya, lihat spesifikasi Hypertext Transfer Protocol dan PATCH Method RFC.
Metode Aman, seperti
HTTP GET dan HEAD, tidak boleh mewakili tindakan selain
pengambilan. Secara khusus, HTTP GET harus dianggap aman dan tidak boleh memiliki efek samping yang terlihat oleh klien.
Idempotensi dalam HTTP
berarti efek samping dari beberapa permintaan identik sama dengan
efek samping untuk satu permintaan. GET, PUT, dan DELETE adalah metode HTTP idempoten yang relevan dengan panduan gaya. Perhatikan bahwa idempotensi hanya dinyatakan dalam hal efek samping server dan tidak menentukan apa pun tentang respons. Secara khusus, DELETE untuk resource yang tidak ada harus menampilkan 404 (Not Found).
HTTP POST dan PATCH tidak aman maupun idempoten. (PATCH was
diperkenalkan di RFC 5789)
| Kata Kerja HTTP | Aman | Idempoten |
|---|---|---|
GET |
Ya | Ya |
PUT |
Ya | |
DELETE |
Ya | |
POST |
||
PATCH |
Format payload
Permintaan dan respons harus memiliki Content-Type yang sama, kecuali jika permintaan adalah
GETatauPOSTdengan isi "application/x-www-form-urlencoded".JSON didukung dalam jenis MIME
application/json. Pemetaan dari proto3 ke JSON secara formal ditentukan dalam Pemetaan JSON.Parameter formulir (
POST) dapat digunakan sebagai pengganti parameter kueri URL (GET), mengikuti aturan pemetaan gaya REST yang sama untuk memetakan kolom permintaan ke parameter kueri.Content-Typeyang didukung adalahapplication/x-www-form-urlencoded.
Streaming
Bagian ini menjelaskan cara Google API menangani streaming klien dan server, khususnya membahas batasan komunikasi half-duplex versus full-duplex dan persyaratan encoding untuk pesan JSON yang di-streaming.
Half-duplex versus full-duplex
HTTP adalah protokol permintaan-respons yang memungkinkan isi permintaan atau responsnya dikirim melalui transportasi berorientasi streaming yang berbeda seperti TCP (HTTP/1.x) atau varian multipleksnya (SPDY, HTTP/2, QUIC).
Sebagai developer klien, aplikasi Anda dapat menghasilkan isi permintaan dalam mode streaming, yaitu streaming klien. Demikian pula, aplikasi juga dapat menggunakan isi respons dalam mode streaming, yaitu streaming server.
Namun, spesifikasi HTTP tidak menentukan apakah server diizinkan untuk melakukan streaming kembali isi respons (kecuali untuk respons error) saat isi permintaan masih tertunda. Semantik ini dikenal sebagai streaming full-duplex. Meskipun banyak program software klien/server/proxy HTTP yang mengizinkan streaming full-duplex, bahkan untuk HTTP/1.1, untuk menghindari masalah interoperabilitas, API cloud berbasis HTTP hanya dibatasi untuk streaming half-duplex.
Secara default, metode streaming bidi di Cloud API mengasumsikan semantik full-duplex. Artinya, tidak aman menggunakan HTTP untuk memanggil metode tersebut. Jika metode streaming hanya half-duplex (seperti yang diterapkan oleh server), dokumen API harus secara jelas menentukan perilaku half-duplex.
Untuk klien browser, semantik HTTP standar dibatasi lebih lanjut oleh Network API browser. Browser mendukung streaming server (yang umumnya menghormati framing tingkat transportasi) menggunakan XHR atau Fetch. Fetch API menggunakan aliran whatwg.
Karena batasan browser, Cloud API yang memerlukan dukungan browser harus menghindari streaming klien serta streaming full-duplex, atau menyediakan API terpisah khusus untuk klien browser.
Secara umum, streaming klien melalui internet kurang berguna dibandingkan streaming server. Hal ini karena penggunaan streaming klien sering kali menyebabkan layanan stateful, yang berdampak buruk pada load balancing dan membuat sistem lebih rentan terhadap kegagalan atau serangan. Di sisi lain, streaming server dapat berguna karena dapat mengurangi latensi secara signifikan melalui jaringan dengan penundaan RTT yang lama.
Encoding pesan
Pesan JSON saat streaming dienkode sebagai array pesan JSON. Isi permintaan atau respons akan tetap sebagai jenis MIME JSON yang valid.
Contoh encoding aliran klien:
1 <length> <message-bytes> 1 <length> <message-bytes> … EOF
Contoh encoding aliran server:
1 <length> <message-bytes> … 2 <length> <status-bytes> EOF
Encoding tingkat kabel: definisi StreamBody hanya signifikan dalam
alokasi tag-id untuk kolom "messages" dan "status" <length> yang
akan dienkode varint dengan 1-2 byte untuk pesan normal, sehingga overhead encoding
total adalah 2-3 byte per pesan.
Kolom padding opsional diperlukan untuk mendukung aliran yang dienkode base64:
message StreamBody {
repeated bytes message = 1;
google.rpc.Status status = 2;
repeated bytes padding = 15; // max one-byte tag-id: xxx01111
}
Pesan error harus ditambahkan sebagai elemen terakhir dari array JSON atau protobuf, dengan format yang sama seperti pesan reguler.
Pengelolaan status
Perilaku half-close ditentukan dengan baik di versi HTTP mana pun agar klien atau server dapat memberi sinyal ke ujung lainnya bahwa isi telah selesai.
Secara khusus, kode klien bebas menyelesaikan permintaan saat masih menunggu respons. Demikian pula, klien mungkin melihat respons yang selesai saat isi permintaan masih ditulis ke server. Standar HTTP mengharapkan klien untuk membatalkan atau menyelesaikan permintaan saat respons selesai dengan cara yang tidak terduga, biasanya dengan status error. Artinya, dalam kondisi normal, server tidak boleh menyelesaikan respons saat klien masih mengirim permintaan.
Pembatalan
Dukungan pembatalan memungkinkan klien membatalkan permintaan saat permintaan atau respons masih tertunda.
Tidak ada dukungan pembatalan yang andal untuk klien HTTP/1.*, karena klien bebas menutup koneksi TCP setelah permintaan selesai tanpa membatalkan transaksi permintaan atau respons. TCP FIN, di HTTP/1.1, tidak boleh diinterpretasikan sebagai pembatalan, meskipun koneksi ditandai sebagai koneksi keep-alive (Connection: Keep-Alive).
Namun, setelah klien menutup koneksi TCP, jika server mencoba menulis data apa pun ke klien, RST akan dibuat, yang dapat memicu pembatalan.
Perhatikan juga bahwa pembatalan juga merupakan masalah untuk API non-streaming. Hal ini terutama terjadi saat respons melibatkan polling panjang sehingga koneksi mungkin tetap tidak aktif untuk jangka waktu yang lama.
Pembatalan eksplisit didukung dengan SPDY, HTTP/2, dan QUIC, terutama dengan pesan go-away.
Keep-alive
Dukungan keep-alive memungkinkan klien atau server mendeteksi peer yang gagal, bahkan jika terjadi kehilangan paket atau kegagalan jaringan.
Tidak ada dukungan keep-alive di HTTP/1.1 karena keep-alive TCP bukanlah pendekatan yang layak.
QUIC atau HTTP/2 menawarkan pesan kontrol khusus untuk tujuan menerapkan dukungan keep-alive oleh aplikasi, termasuk browser.
Namun, keep-alive dan deteksi kegagalan yang andal kemungkinan akan memerlukan library klien dengan dukungan sisi server yang diperlukan: melakukan streaming jangka panjang melalui internet sering kali rentan error jika mengandalkan HTTP dasar sebagai protokol komunikasi.
Kontrol alur
Dukungan kontrol alur mengharuskan klien menyebarkan peristiwa kontrol alur tingkat transportasi ke aplikasi klien. Mekanisme sebenarnya bergantung pada gaya HTTP client API yang digunakan aplikasi klien Anda. Misalnya, Anda memerlukan penulisan dan pembacaan yang memblokir, atau pembacaan dan penulisan yang tidak memblokir dengan dukungan kontrol alur eksplisit agar aplikasi dapat menangani dan menghormati peristiwa kontrol alur, untuk mencegah klien atau server kelebihan beban.
HTTP/1.1 mengandalkan kontrol alur TCP.
SPDY dan HTTP/2 memiliki kontrol alur sendiri di tingkat aliran, yang selanjutnya tunduk pada kontrol alur TCP di tingkat koneksi karena permintaan di-multipleks melalui satu koneksi TCP.
QUIC berjalan di UDP dan oleh karena itu mengelola kontrol alur sepenuhnya.