Memahami cara kerja Google API dengan berbagai versi dan penerapan HTTP penting jika Anda menulis kode kustom yang mengakses antarmuka REST API menggunakan klien HTTP pihak ketiga. Untuk sebagian besar beban kerja, gunakan library klien yang direkomendasikan Google, yang secara otomatis menangani komunikasi server tingkat rendah yang dibahas dalam dokumen ini.
Bekerja dengan protokol melalui 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 yang kami rekomendasikan untuk menggunakannya.
Semantik HTTP
Saat mengembangkan kode klien API, ikuti semantik protokol HTTP standar. Proxy sisi server atau stack API mungkin hanya mendukung subset fitur HTTP standar, dan mungkin juga mendukung versi yang kompatibel dengan versi lama.
Semantik protokol HTTP yang perlu ditangani oleh implementasi API sisi server dikontrol oleh stack server. Hanya mengandalkan 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, sebagaimana diizinkan oleh platform klien atau jaringan sisi klien, atau sebagaimana 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 dianjurkan.
Beberapa fitur API mungkin hanya didukung oleh versi protokol HTTP yang lebih baru; beberapa hanya ditentukan sepenuhnya 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, sebaiknya gunakan HTTP/3 atau HTTP/2 untuk performa yang lebih baik, mengurangi pemblokiran head-of-line, dan ketahanan yang lebih besar terhadap kegagalan jaringan.
Saluran
Saluran mengacu pada koneksi jaringan Lapisan 4, yang biasanya berupa 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; pipelining HTTP 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, sehingga memungkinkan beberapa permintaan dan respons dikirim secara bersamaan melalui satu koneksi.
- HTTP/2—menggunakan satu koneksi TCP per origin.
- HTTP/3—menggunakan satu koneksi QUIC melalui UDP per origin. 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 data.
Dengan HTTP/2 dan HTTP/3, batas 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 batas pada jumlah maksimum streaming serentak dalam satu koneksi HTTP/2 atau HTTP/3. Hal ini mencegah kelebihan beban dan memastikan penggunaan resource yang adil (misalnya, dengan membatasi permintaan serentak atau streaming 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 bagi aplikasi klien. Secara default, Google API hanya menerima traffic HTTPS.
Format permintaan dan respons
Bagian ini menjelaskan struktur interaksi API, termasuk penggunaan data berenkode 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 HTTP serta respons menggunakan application/json sebagai Content-Type.
Isi HTTP menggunakan array JSON untuk mendukung metode RPC yang di-streaming, dan array JSON dapat berisi sejumlah pesan JSON atau pesan JSON status error.
URL permintaan yang 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 mengabaikan batasan, kode klien harus menggunakan permintaan POST dengan
Content-Type application/x-www-form-urlencoded beserta 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 ditentukan sebagai bagian dari spesifikasi API. Secara khusus, setiap metode API harus mematuhi persyaratan protokol HTTP berdasarkan kata kerja HTTP tertentu yang dipetakan oleh metode API. Untuk mengetahui informasi selengkapnya, lihat spesifikasi Hypertext Transfer Protocol dan RFC Metode PATCH.
Metode Aman, seperti HTTP GET dan HEAD, tidak boleh merepresentasikan tindakan selain pengambilan. Secara khusus, HTTP GET harus dianggap aman dan
tidak boleh memiliki efek samping yang terlihat oleh klien.
Idempotensi di HTTP
berarti bahwa efek samping dari beberapa permintaan yang identik sama dengan
untuk satu permintaan. GET, PUT, dan DELETE adalah metode HTTP idempoten yang relevan dengan panduan gaya penulisan. Perhatikan bahwa idempoten hanya
dinyatakan dalam hal efek samping sisi server dan tidak menentukan apa pun
tentang respons. Secara khusus, DELETE untuk resource yang tidak ada
harus menampilkan 404 (Not Found).
POST dan PATCH HTTP tidak aman dan tidak idempoten. (PATCH 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 ditentukan secara formal 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 berbagai transpor berorientasi streaming 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 balik 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 bersifat half-duplex saja (seperti yang diterapkan oleh server), dokumen API harus secara jelas menentukan perilaku half-duplex.
Untuk klien browser, semantik HTTP standar lebih dibatasi oleh API Jaringan browser. Browser mendukung streaming server (yang umumnya mengikuti framing tingkat transpor) menggunakan XHR atau Fetch. Fetch API menggunakan whatwg streams.
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 streaming klien:
1 <length> <message-bytes> 1 <length> <message-bytes> … EOF
Contoh encoding streaming 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 total overhead encoding adalah 2-3 byte per pesan.
Kolom padding opsional diperlukan untuk mendukung streaming berenkode 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, dalam format yang sama dengan pesan biasa.
Pengelolaan status
Perilaku setengah tutup didefinisikan dengan baik di versi HTTP mana pun bagi klien atau server untuk 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 telah selesai saat isi permintaan masih ditulis ke server. Standar HTTP mengharapkan klien 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 bawah HTTP/1.1, tidak boleh ditafsirkan sebagai pembatalan, bahkan saat koneksi ditandai sebagai 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 menjadi masalah untuk API non-streaming. Hal ini terutama terjadi saat respons melibatkan polling panjang sehingga koneksi mungkin tetap tidak aktif dalam jangka waktu yang lama.
Pembatalan eksplisit didukung dengan SPDY, HTTP/2, dan QUIC, terutama dengan pesan go-away.
Keep-alive
Dukungan tetap aktif 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 penerapan 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 yang berjalan lama melalui internet sering kali rentan terhadap 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 API klien HTTP yang digunakan aplikasi klien Anda. Misalnya, Anda memerlukan penulisan dan pembacaan blocking, atau pembacaan dan penulisan yang tidak memblokir dengan dukungan kontrol alur eksplisit agar aplikasi dapat menangani dan mematuhi 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 streaming, yang selanjutnya tunduk pada kontrol alur TCP di tingkat koneksi karena permintaan di-multiplexing melalui satu koneksi TCP.
QUIC berjalan di UDP dan oleh karena itu mengelola kontrol alur sepenuhnya sendiri.