Dokumen ini menjelaskan dasar-dasar protokol yang digunakan oleh Google Data API, termasuk contoh tampilan kueri, tampilan hasil, dan sebagainya.
Untuk informasi selengkapnya tentang Google Data API, lihat dokumen Panduan Developer Data Google dan Panduan Referensi.
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.
Contoh
Contoh berikut menunjukkan permintaan protokol Data API sederhana yang mungkin Anda kirim ke layanan generik, 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 penggunaan Google Data API 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 berikut ke server:
GET /myFeed
Server merespons:
200 OK <?xml version="1.0"?> <feed xmlns="http://www.w3.org/2005/Atom"> <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.
Menyisipkan entri baru
Untuk membuat entri baru, kirim permintaan POST
, dan berikan representasi XML dari entri baru:
POST /myFeed <?xml version="1.0"?> <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"?> <entry xmlns="http://www.w3.org/2005/Atom"> <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 semua entri yang cocok dengan string penelusuran This
. (Dalam hal ini hanya ada satu.)
200 OK <?xml version="1.0"?> <feed xmlns="http://www.w3.org/2005/Atom"> <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> <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> </feed>
Memperbarui entri
Untuk memperbarui entri yang ada, gunakan PUT
, dengan URI edit entri (seperti yang disediakan oleh server dalam contoh sebelumnya, di elemen <link rel="edit">
).
Jika firewall Anda tidak mengizinkan PUT
, lakukan HTTP POST
dan setel header penggantian metode sebagai berikut:
X-HTTP-Method-Override: PUT
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"?> <entry xmlns="http://www.w3.org/2005/Atom"> <id>http://www.example.com/id/1</id> <link rel="edit" href="http://example.com/myFeed/1/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"?> <entry xmlns="http://www.w3.org/2005/Atom"> <id>http://www.example.com/id/1</id> <link rel="edit" href="http://example.com/myFeed/1/2/"/> <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 URI edit telah berubah; sekarang diakhiri dengan "/2/", bukan "/1/". Nomor final dalam URI edit adalah nomor versi. Untuk mengetahui informasi selengkapnya tentang versi, lihat bagian Serentak optimis di dokumen referensi protokol.
Untuk melihat entri baru dalam konteks, minta seluruh resource lagi:
GET /myFeed
Server merespons:
200 OK <?xml version="1.0"?> <feed xmlns="http://www.w3.org/2005/Atom"> <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> <id>http://www.example.com/id/1</id> <link rel="edit" href="http://example.com/myFeed/1/2/"/> <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>
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
Contoh berikut menghapus entri:
DELETE /myFeed/1/2/
Server merespons:
200 OK
Lakukan GET
lain untuk melihat bahwa feed sekarang tidak berisi entri:
GET /myFeed
Server merespons:
200 OK <?xml version="1.0"?> <feed xmlns="http://www.w3.org/2005/Atom"> <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.
Referensi lainnya
Dokumen pihak ketiga berikut mungkin berguna untuk Anda:
- Ringkasan Atom dari IBM
- Definisi metode HTTP 1.1; spesifikasi untuk
GET
,POST
,PUT
, danDELETE
- Definisi kode status HTTP 1.1
- Cara Membuat Protokol REST
- Membuat Layanan Web dengan Cara REST
- Pengantar Teknis XML
- Namespace XML berdasarkan Contoh