Metode kustom

Bab ini akan membahas cara menggunakan metode kustom untuk desain API.

Metode kustom merujuk pada metode API selain 5 metode standar. Parameter seharusnya hanya digunakan untuk fungsi yang tidak dapat dinyatakan dengan mudah melalui metode standar. Secara umum, desainer API harus memilih metode standar, bukan metode kustom, jika memungkinkan. Metode Standar memiliki semantik yang lebih sederhana dan didefinisikan dengan baik yang sudah dikenal oleh sebagian besar developer, sehingga lebih mudah digunakan dan lebih jarang menimbulkan error. Keuntungan lain dari metode standar adalah platform API memiliki pemahaman dan dukungan yang lebih baik untuk metode standar, seperti penagihan, penanganan error, logging, pemantauan.

Metode kustom dapat dikaitkan dengan resource, koleksi, atau layanan. Aplikasi mungkin mengambil permintaan arbitrer dan menampilkan respons arbitrer, serta mendukung permintaan dan respons streaming.

Nama metode kustom harus mengikuti konvensi penamaan metode.

Pemetaan HTTP

Untuk metode kustom, metode tersebut harus menggunakan pemetaan HTTP generik berikut:

https://service.name/v1/some/resource/name:customVerb

Alasan menggunakan :, bukan /, untuk memisahkan kata kerja kustom dari nama resource adalah untuk mendukung jalur arbitrer. Misalnya, membatalkan penghapusan file dapat dipetakan ke POST /files/a/long/file/name:undelete

Panduan berikut akan diterapkan saat memilih pemetaan HTTP:

Metode kustom harus menggunakan verb POST HTTP karena memiliki semantik yang paling fleksibel, kecuali untuk metode yang ditayangkan sebagai get atau daftar alternatif yang mungkin menggunakan GET jika memungkinkan. (Lihat butir ketiga untuk mengetahui detailnya.)
Metode kustom tidak boleh menggunakan HTTP PATCH, tetapi dapat menggunakan kata kerja HTTP lainnya. Dalam kasus semacam itu, metode tersebut harus mengikuti semantik HTTP standar untuk kata kerja tersebut.
Secara khusus, metode kustom yang menggunakan GET HTTP harus bersifat idempoten dan tidak memiliki efek samping. Misalnya, metode kustom yang mengimplementasikan tampilan khusus pada resource harus menggunakan HTTP GET.
Kolom pesan permintaan yang menerima nama resource dari resource atau koleksi yang terkait dengan metode kustom harus dipetakan ke jalur URL.
Jalur URL harus diakhiri dengan akhiran yang terdiri dari titik dua diikuti dengan kata kerja kustom.
Jika kata kerja HTTP yang digunakan untuk metode kustom mengizinkan isi permintaan HTTP (ini berlaku untuk POST, PUT, PATCH, atau kata kerja HTTP kustom), konfigurasi HTTP metode kustom tersebut harus menggunakan klausa body: "*" dan semua kolom pesan permintaan yang tersisa harus dipetakan ke isi permintaan HTTP.
Jika kata kerja HTTP yang digunakan untuk metode kustom tidak menerima isi permintaan HTTP (GET, DELETE), konfigurasi HTTP metode tersebut tidak boleh menggunakan klausa body sama sekali, dan semua kolom pesan permintaan yang tersisa akan dipetakan ke parameter kueri URL.

PERINGATAN: Jika layanan mengimplementasikan beberapa API, produser API harus dengan cermat membuat konfigurasi layanan untuk menghindari konflik kata kerja kustom antar-API.

// This is a service level custom method.
rpc Watch(WatchRequest) returns (WatchResponse) {
  // Custom method maps to HTTP POST. All request parameters go into body.
  option (google.api.http) = {
    post: "/v1:watch"
    body: "*"
  };
}

// This is a collection level custom method.
rpc ClearEvents(ClearEventsRequest) returns (ClearEventsResponse) {
  option (google.api.http) = {
    post: "/v3/events:clear"
    body: "*"
  };
}

// This is a resource level custom method.
rpc CancelEvent(CancelEventRequest) returns (CancelEventResponse) {
  option (google.api.http) = {
    post: "/v3/{name=events/*}:cancel"
    body: "*"
  };
}

// This is a batch get custom method.
rpc BatchGetEvents(BatchGetEventsRequest) returns (BatchGetEventsResponse) {
  // The batch get method maps to HTTP GET verb.
  option (google.api.http) = {
    get: "/v3/events:batchGet"
  };
}

Kasus Penggunaan

Beberapa skenario tambahan saat metode kustom mungkin merupakan pilihan yang tepat:

Mulai ulang virtual machine. Alternatif desain dapat berupa "membuat resource mulai ulang dalam kumpulan reboot" yang terasa sangat kompleks, atau "mesin virtual memiliki status yang dapat diubah yang dapat diperbarui klien dari RUNNING ke RESTARTING" yang akan membuka pertanyaan tentang transisi status lainnya yang mungkin dilakukan. Selain itu, mulai ulang adalah konsep terkenal yang dapat diterjemahkan dengan baik ke metode kustom yang secara intuitif memenuhi ekspektasi developer.
Kirim email. Membuat pesan email tidak harus selalu mengirimkannya (draf). Dibandingkan dengan alternatif desain (memindahkan pesan ke koleksi "Kotak Keluar"), metode kustom memiliki keuntungan karena lebih mudah ditemukan oleh pengguna API dan memodelkan konsep secara lebih langsung.
Mempromosikan karyawan. Jika diterapkan sebagai update standar, klien harus mereplikasi kebijakan perusahaan yang mengatur proses promosi untuk memastikan promosi terjadi di tingkat yang benar, dalam tangga karier yang sama, dll.
Metode batch. Untuk metode yang kritis performa, sebaiknyamenyediakanmetode batch kustom untuk mengurangi overhead per permintaan. Misalnya, accounts.locations.batchGet.

Beberapa contoh ketika metode standar lebih cocok daripada metode kustom:

Resource kueri dengan parameter kueri yang berbeda (gunakan metode list standar dengan pemfilteran daftar standar).
Perubahan properti resource sederhana (gunakan metode update standar dengan mask kolom).
Menutup notifikasi (gunakan metode delete standar).

Metode Khusus Umum

Daftar pilihan nama metode kustom yang biasa digunakan atau berguna dapat dilihat di bawah. Desainer API harus mempertimbangkan nama ini sebelum memperkenalkan nama mereka sendiri untuk memfasilitasi konsistensi di seluruh API.

Nama Metode	Kata kerja kustom	Kata kerja HTTP	Catatan
`Cancel`	`:cancel`	`POST`	Batalkan operasi yang belum terselesaikan, seperti `operations.cancel`.
`BatchGet`	`:batchGet`	`GET`	Mendapatkan beberapa resource sekaligus. Lihat detail di deskripsi List.
`Move`	`:move`	`POST`	Memindahkan resource dari satu induk ke induk lainnya, seperti `folders.move`.
`Search`	`:search`	`GET`	Alternatif bagi List untuk mengambil data yang tidak mematuhi semantik List, seperti `services.search`.
`Undelete`	`:undelete`	`POST`	Memulihkan resource yang sebelumnya dihapus, seperti `services.undelete`. Periode retensi yang direkomendasikan adalah 30 hari.