Dasar-dasar Protokol

Peringatan: Halaman ini membahas API lama Google, yaitu Google Data API; halaman ini hanya relevan dengan API yang tercantum dalam direktori Google Data API, banyak di antaranya telah diganti dengan API yang lebih baru. Untuk informasi tentang API baru tertentu, lihat dokumentasi API baru. Untuk informasi tentang memberi otorisasi permintaan dengan API baru, lihat Autentikasi dan Otorisasi Akun Google.

Dokumen ini menjelaskan dasar-dasar Protokol Data Google yang digunakan oleh banyak Google API, termasuk contoh tampilan kueri, tampilan hasil, dan sebagainya.

Untuk informasi selengkapnya tentang Protokol Data Google, lihat halaman ringkasan Panduan Developer dan Referensi Protokol.

Audiens

Dokumen ini ditujukan bagi siapa saja yang ingin memahami ide umum tentang format XML dan protokol yang digunakan oleh Google Data API.

Meskipun Anda hanya ingin menulis kode yang menggunakan library klien spesifik bahasa, Anda mungkin ingin membaca dokumen ini untuk memahami apa yang terjadi di bawah lapisan abstraksi library klien.

Dokumen ini mengasumsikan bahwa Anda memahami dasar-dasar XML, namespace, feed yang dipublikasikan, serta permintaan GET, POST, PUT, dan DELETE di HTTP, serta konsep HTTP tentang "resource". Untuk informasi selengkapnya tentang hal-hal tersebut, lihat bagian Referensi tambahan dalam dokumen ini.

Dokumen ini tidak bergantung pada bahasa pemrograman tertentu. Klien Anda dapat berinteraksi dengan server menggunakan bahasa pemrograman apa pun yang memungkinkan Anda mengeluarkan permintaan HTTP dan mengurai respons berbasis XML.

Jika Anda ingin mencoba contoh dalam dokumen ini tanpa harus menulis kode apa pun, Anda dapat menggunakan cURL utilitas baris perintah atau Wget; untuk informasi selengkapnya, lihat halaman manual untuk utilitas tersebut atau dokumen tentang Menggunakan cURL untuk berinteraksi dengan layanan yang menggunakan Protokol Data Google.

Contoh

Contoh berikut menunjukkan permintaan HTTP yang mungkin Anda kirim ke layanan generik menggunakan protokol Google Data Protocol API secara langsung, dan hasil yang mungkin Anda terima. Untuk contoh cara mengirim permintaan menggunakan berbagai bahasa pemrograman, lihat sampel dan library klien khusus bahasa. Untuk informasi tentang cara menggunakan Protokol Data Google dengan layanan Google tertentu, lihat dokumentasi khusus layanan.

Meminta feed atau resource lainnya

Anggaplah ada feed yang bernama /myFeed, dan asumsikan bahwa feed tersebut saat ini tidak berisi entri apa pun. Untuk melihatnya, kirim permintaan HTTP berikut ke server:

GET /myFeed

Server merespons:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <title>Foo</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

Perlu diketahui bahwa meskipun feed tidak berisi entri apa pun, feed tersebut berisi metadata, seperti judul dan nama penulis. Class ini juga berisi ID versi, dalam bentuk HTTP ETag.

Menyisipkan entri baru

Untuk membuat entri baru, kirim permintaan POST, dan berikan representasi XML dari entri baru:

POST /myFeed

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

Perhatikan bahwa Anda tidak menyediakan elemen <id>, <link>, atau <updated> Atom standar; server akan membuatnya sebagai respons terhadap permintaan POST Anda. Harap diingat juga bahwa penulis feed tidak harus sama dengan orang yang menulis penulis sebuah entri.

Server merespons:

201 CREATED

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/1/'/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

Menelusuri string

Untuk melakukan penelusuran teks lengkap pada string tertentu, saat menggunakan layanan yang mendukung penelusuran teks lengkap, kirim permintaan GET dengan parameter q. Untuk informasi selengkapnya tentang parameter kueri, lihat Permintaan kueri dalam dokumen referensi protokol.

GET /myFeed?q=This

Server merespons dengan feed yang berisi semua entri yang cocok dengan string penelusuran This. (Dalam hal ini hanya ada satu.)

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"S0wCTlpIIip7ImA0X0QI"'>
  <title>Foo</title>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my entry</content>
  </entry>
</feed>

Memperbarui entri

Untuk memperbarui entri yang ada, Anda perlu melakukan langkah-langkah berikut.

  1. Ambil entri yang ingin Anda perbarui.
  2. Ubah sesuai keinginan.
  3. Kirim permintaan PUT, dengan entri yang diperbarui dalam isi pesan, ke URI edit entri. URI edit muncul dalam contoh sebelumnya sebagai atribut href dari elemen <link rel='edit'>.

Anda juga harus menentukan ETag entri awal untuk memastikan bahwa Anda tidak menimpa perubahan yang dilakukan orang lain.

Dalam contoh berikut, kami mengubah teks entri dari nilai lamanya ("Ini adalah entri saya") ke nilai baru ("Ini adalah entri pertama saya"):

PUT /myFeed/1/1/

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

Server merespons:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

Perhatikan bahwa ETag telah berubah. Untuk informasi selengkapnya tentang versi resource, lihat bagian Pembuatan versi resource (ETag) dalam dokumen referensi protokol.

Untuk melihat entri baru dalam konteks, minta seluruh resource lagi:

GET /myFeed

Server merespons:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D08FQn8-eil7ImA9WxZbFEw."'>
  <title>Foo</title>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:28:05-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my first entry.</content>
  </entry>
</feed>

Catatan: Jika firewall Anda tidak mengizinkan PUT, lakukan HTTP POST dan setel header penggantian metode sebagai berikut:

X-HTTP-Method-Override: PUT

Menghapus entri

Untuk menghapus entri yang ada, kirim permintaan DELETE menggunakan URI edit entri (seperti yang disediakan oleh server dalam contoh sebelumnya).

Jika firewall Anda tidak mengizinkan DELETE, lakukan HTTP POST dan setel header penggantian metode sebagai berikut:

X-HTTP-Method-Override: DELETE

Saat menghapus entri, Anda dapat memilih apakah akan melakukan penghapusan bersyarat (hanya menghapus jika entri tidak berubah sejak terakhir kali Anda mengambilnya) atau penghapusan tanpa syarat. Untuk informasi selengkapnya, lihat bagian Pembuatan versi resource (ETag) dalam dokumen referensi protokol. Untuk melakukan penghapusan tanpa syarat, setel header HTTP berikut:

If-Match: *

Contoh berikut menghapus entri (jika header disetel dengan sesuai):

DELETE /myFeed/1/

Server merespons:

200 OK

Lakukan GET lain untuk melihat bahwa feed sekarang tidak berisi entri:

GET /myFeed

Server merespons dengan feed yang hanya berisi metadata:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
  <title>Foo</title>
  <updated>2006-01-23T16:30:11-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

Jika penghapusan gagal, server akan merespons dengan kode error. Untuk informasi selengkapnya, lihat Kode status HTTP di dokumen referensi protokol.

Meminta feed atau entri parsial (Eksperimental)

Berbeda dengan feed contoh sederhana yang ditampilkan dalam dokumen ini, dalam praktiknya, feed dapat menjadi cukup rumit. Dengan beberapa API, Anda hanya dapat meminta elemen atau atribut yang diminati, bukan representasi resource lengkap. Saat Anda menghindari pengambilan dan penguraian data yang tidak diperlukan, Anda dapat meningkatkan efisiensi aplikasi klien Anda secara signifikan.

Untuk meminta respons parsial, gunakan parameter kueri fields untuk menentukan elemen atau atribut mana yang ingin Anda tampilkan. Untuk mengetahui informasi selengkapnya, lihat Respons sebagian di dokumen referensi protokol.

Contoh berikut hanya meminta ID feed, serta penulis dan judul untuk setiap entri feed,

GET /myFeed?fields=id,entry(author)

Server merespons:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://www.example.com/myFeed</id>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
  </entry>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 2</title>
  </entry>
</feed>

Anda dapat menggunakan parameter fields dengan jenis permintaan apa pun yang menampilkan data. Selain GET, ini termasuk POST, dan PUT (serta PATCH, yang digunakan untuk membuat permintaan pembaruan sebagian).

Catatan: Parameter kueri fields hanya mengontrol data yang dikirim kembali sebagai respons terhadap permintaan; parameter ini tidak memengaruhi data yang harus Anda berikan dalam isi permintaan PUT, POST, atau PATCH.

Contoh untuk POST dan PUT ditunjukkan di bawah ini.

  • Saat membuat permintaan POST untuk respons parsial, Anda tetap harus menyediakan data yang sama seperti yang dijelaskan di Menyisipkan entri baru. Contoh berikut meminta respons parsial yang hanya berisi judul entri yang baru dibuat: 
    POST /myFeed?fields=title
      
...data...

    Server merespons:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Entry 1</title>
</entry>
  • Saat membuat permintaan PUT untuk respons sebagian, Anda masih harus memberikan versi modifikasi representasi resource lengkap, seperti yang dijelaskan dalam Memperbarui entri. Contoh berikut meminta respons parsial yang hanya berisi nilai ETag baru untuk entri yang diubah: 
    PUT /myFeed/1/1?fields=@gd:etag
  
...data...

    Server merespons:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
  gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>

Memperbarui kolom tertentu (Eksperimental)

Jika API yang Anda gunakan mendukung respons parsial dan memiliki kolom yang dapat diedit, Anda juga dapat menghindari pengiriman data yang tidak diperlukan saat memodifikasi entri. Update sebagian memungkinkan Anda mengirim data hanya untuk kolom yang ingin diubah.

Untuk menggunakan update parsial, kirim permintaan PATCH ke URI edit yang sama dengan yang Anda gunakan dengan PUT. Data yang Anda kirim dengan PATCH harus mengikuti konvensi tertentu. Namun, semantik cukup fleksibel bagi Anda untuk mengganti data dalam resource target, menambahkannya, atau bahkan melakukan penghapusan dari resource tersebut, semuanya dengan satu permintaan.

Catatan: Seperti pada PUT, Anda harus menentukan ETag entri asli untuk memastikan perubahan yang dibuat orang lain tidak ditimpa.

Untuk mengetahui informasi selengkapnya tentang PATCH dan semantiknya, lihat Update sebagian dalam dokumen referensi protokol.

Contoh ini menunjukkan permintaan update parsial yang memodifikasi judul entri:

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag="EksPTg1Bfyp7IWA6WhJT"
    gd:fields='title'>
  <title>New Title</title>
</entry>

Saat menerima permintaan PATCH, server akan menghapus kolom apa pun yang ditentukan oleh atribut gd:fields entri (jika ada); pertama-tama, server akan menggabungkan data yang disediakan dalam isi permintaan dengan resource target. Dalam contoh ini, elemen judul pertama-tama dihapus dari resource target, lalu nilai judul baru digabungkan. Secara efektif, permintaan ini mengganti judul lama dengan yang baru.

Namun, perlu diperhatikan bahwa semantik PATCH adalah untuk menggabungkan representasi parsial ke dalam resource yang ada. Anda tidak harus menghapus kolom untuk memperbarui nilainya.

  • Jika kolom hanya bisa ada sekali di entri target, pada saat penggabungan, kolom di representasi parsial akan menimpa kolom yang sesuai di entri target.
  • Jika kolom dapat ada lebih dari sekali di entri target, maka saat menggabungkan, kolom parsial akan ditambahkan ke entri target.

Perbedaan antara penggabungan kolom berulang dan non-pengulangan ditunjukkan oleh contoh berikutnya, yang menambahkan judul dan penulis baru ke entri tanpa menggunakan atribut gd:fields untuk menghapus salah satunya terlebih dahulu.

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:edtag="EksPTg1Bfyp7IWA6WhJT">
  <title>A new title</title>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>darcy@gmail.com</email>
  </author>
</entry>

Karena representasi entri parsial tidak memiliki atribut gd:fields, tidak ada kolom yang dihapus. Namun, nilai baru untuk elemen <title> dan <author> digabungkan dengan resource target:

  • Karena Atom hanya mengizinkan satu judul per entri, judul yang baru akan menimpa nilai yang ada. 
  • Karena Atom memungkinkan beberapa penulis per entri, penulis baru ditambahkan ke daftar elemen penulis yang sudah ada di resource target.

    Catatan: Tidak semua API sesuai dengan standar Atom. Misalnya, beberapa API hanya mengizinkan satu elemen <author> per entri; sedangkan yang lainnya mewarisi penulis entri dari tingkat feed, sehingga kolom ini menjadi hanya baca.

Setelah server memproses permintaan PATCH yang valid, server akan menampilkan kode status 200 HTTP, beserta salinan representasi lengkap dari entri yang diperbarui.

Jika Anda ingin server hanya menampilkan elemen atau atribut tertentu, Anda dapat menggunakan parameter kueri fields dengan PATCH untuk meminta respons parsial.

Referensi lainnya

Dokumen pihak ketiga berikut mungkin berguna untuk Anda:

Kembali ke atas