Metode standar

Bab ini menjelaskan konsep metode standar, yaitu List, Get, Create, Update, dan Delete. Metode standar mengurangi kompleksitas dan meningkatkan konsistensi. Lebih dari 70% metode API di repositori Google API adalah metode standar, yang membuatnya jauh lebih mudah untuk dipelajari dan digunakan.

Tabel berikut menjelaskan cara memetakan metode standar ke metode HTTP:

Metode Standar Pemetaan HTTP Isi Permintaan HTTP Isi Respons HTTP
List GET <collection URL> T/A Daftar aset*
Get GET <resource URL> T/A Referensi*
Create POST <collection URL> Resource Referensi*
Update PUT or PATCH <resource URL> Resource Referensi*
Delete DELETE <resource URL> T/A google.protobuf.Empty**

*Resource yang ditampilkan dari metode List, Get, Create, dan Update dapat berisi sebagian data jika metode tersebut mendukung mask kolom respons, yang menentukan subset kolom yang akan ditampilkan. Dalam beberapa kasus, platform API secara native mendukung mask kolom untuk semua metode.

**Respons yang ditampilkan dari metode Delete yang tidak segera menghapus resource (seperti memperbarui flag atau membuat operasi penghapusan yang berjalan lama) harus berisi operasi yang berjalan lama atau resource yang diubah.

Metode standar dapat juga menampilkan operasi yang berjalan lama untuk permintaan yang tidak selesai dalam rentang waktu panggilan API tunggal.

Bagian berikut menjelaskan setiap metode standar secara mendetail. Contoh ini menunjukkan metode yang ditentukan dalam file .proto dengan anotasi khusus untuk pemetaan HTTP. Anda dapat menemukan banyak contoh yang menggunakan metode standar di repositori Google API.

Daftar

Metode List menggunakan nama koleksi dan nol atau beberapa parameter sebagai input, serta menampilkan daftar resource yang cocok dengan input tersebut.

List biasanya digunakan untuk menelusuri resource. List cocok untuk data dari satu koleksi yang dibatasi ukuran dan tidak di-cache. Untuk kasus yang lebih luas, metode kustom Search harus digunakan.

Batch get (seperti metode yang menggunakan beberapa ID resource dan menampilkan objek untuk setiap ID tersebut) harus diimplementasikan sebagai metode BatchGet kustom, bukan List. Namun, jika memiliki metode List yang sudah ada dan menyediakan fungsi yang sama, Anda dapat menggunakan kembali metode List untuk tujuan ini. Jika Anda menggunakan metode BatchGet kustom, metode tersebut harus dipetakan ke HTTP GET.

Pola umum yang berlaku: penomoran halaman, pengurutan hasil.

Konvensi penamaan yang berlaku: kolom filter, kolom hasil

Pemetaan HTTP:

  • Metode List harus menggunakan kata kerja GET HTTP.
  • Kolom pesan permintaan yang menerima nama koleksi yang resource-nya tercantum harus dipetakan ke jalur URL. Jika nama koleksi dipetakan ke jalur URL, segmen terakhir template URL (ID koleksi) harus berupa literal.
  • Semua kolom pesan permintaan yang tersisa akan dipetakan ke parameter kueri URL.
  • Tidak ada isi permintaan; konfigurasi API tidak boleh mendeklarasikan klausa body.
  • Isi respons harus berisi daftar resource beserta metadata opsional.

Contoh:

// Lists books in a shelf.
rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
  // List method maps to HTTP GET.
  option (google.api.http) = {
    // The `parent` captures the parent resource name, such as "shelves/shelf1".
    get: "/v1/{parent=shelves/*}/books"
  };
}

message ListBooksRequest {
  // The parent resource name, for example, "shelves/shelf1".
  string parent = 1;

  // The maximum number of items to return.
  int32 page_size = 2;

  // The next_page_token value returned from a previous List request, if any.
  string page_token = 3;
}

message ListBooksResponse {
  // The field name should match the noun "books" in the method name.  There
  // will be a maximum number of items returned based on the page_size field
  // in the request.
  repeated Book books = 1;

  // Token to retrieve the next page of results, or empty if there are no
  // more results in the list.
  string next_page_token = 2;
}

Dapatkan

Metode Get mengambil nama resource, nol atau beberapa parameter, dan menampilkan resource yang ditentukan.

Pemetaan HTTP:

  • Metode Get harus menggunakan kata kerja GET HTTP.
  • Kolom pesan permintaan yang menerima nama resource harus dipetakan ke jalur URL.
  • Semua kolom pesan permintaan yang tersisa akan dipetakan ke parameter kueri URL.
  • Tidak ada isi permintaan; konfigurasi API tidak boleh mendeklarasikan klausa body.
  • Resource yang ditampilkan akan dipetakan ke seluruh isi respons.

Contoh:

// Gets a book.
rpc GetBook(GetBookRequest) returns (Book) {
  // Get maps to HTTP GET. Resource name is mapped to the URL. No body.
  option (google.api.http) = {
    // Note the URL template variable which captures the multi-segment resource
    // name of the requested book, such as "shelves/shelf1/books/book2"
    get: "/v1/{name=shelves/*/books/*}"
  };
}

message GetBookRequest {
  // The field will contain name of the resource requested, for example:
  // "shelves/shelf1/books/book2"
  string name = 1;
}

Buat

Metode Create menggunakan nama resource induk, resource, dan nol atau beberapa parameter. Opsi ini membuat resource baru di bawah induk yang ditentukan, dan menampilkan resource yang baru dibuat.

Jika mendukung pembuatan resource, API harus memiliki metode Create untuk setiap jenis resource yang dapat dibuat.

Pemetaan HTTP:

  • Metode Create harus menggunakan kata kerja POST HTTP.
  • Pesan permintaan harus memiliki kolom parent yang menentukan nama resource induk tempat resource akan dibuat.
  • Kolom pesan permintaan yang berisi resource harus dipetakan ke isi permintaan HTTP. Jika anotasi google.api.http digunakan untuk metode Create, bentuk body: "<resource_field>" harus digunakan.
  • Permintaan tersebut mungkin berisi kolom bernama <resource>_id untuk memungkinkan pemanggil memilih ID yang ditetapkan klien. Kolom ini mungkin ada di dalam resource.
  • Semua kolom pesan permintaan yang tersisa akan dipetakan ke parameter kueri URL.
  • Resource yang ditampilkan akan dipetakan ke seluruh isi respons HTTP.

Jika metode Create mendukung nama resource yang ditetapkan klien dan resource sudah ada, permintaan akan gagal dengan kode error ALREADY_EXISTS atau menggunakan nama resource lain yang ditetapkan server dan dokumentasi harus jelas bahwa nama resource yang dibuat mungkin berbeda dari yang diteruskan.

Metode Create harus mengambil resource input, sehingga saat skema resource berubah, skema permintaan dan skema resource tidak perlu diperbarui. Untuk kolom resource yang tidak dapat ditetapkan oleh klien, kolom tersebut harus didokumentasikan sebagai kolom "Hanya output".

Contoh:

// Creates a book in a shelf.
rpc CreateBook(CreateBookRequest) returns (Book) {
  // Create maps to HTTP POST. URL path as the collection name.
  // HTTP request body contains the resource.
  option (google.api.http) = {
    // The `parent` captures the parent resource name, such as "shelves/1".
    post: "/v1/{parent=shelves/*}/books"
    body: "book"
  };
}

message CreateBookRequest {
  // The parent resource name where the book is to be created.
  string parent = 1;

  // The book id to use for this book.
  string book_id = 3;

  // The book resource to create.
  // The field name should match the Noun in the method name.
  Book book = 2;
}

rpc CreateShelf(CreateShelfRequest) returns (Shelf) {
  option (google.api.http) = {
    post: "/v1/shelves"
    body: "shelf"
  };
}

message CreateShelfRequest {
  Shelf shelf = 1;
}

Pembaruan

Metode Update mengambil pesan permintaan yang berisi resource serta nol atau beberapa parameter. Library ini memperbarui resource yang ditentukan dan propertinya, serta menampilkan resource yang diperbarui.

Properti resource yang dapat diubah harus dapat diubah oleh metode Update, kecuali properti yang berisi nama atau induk resource. Fungsionalitas apa pun untuk mengganti nama atau memindahkan resource tidak boleh terjadi dalam metode Update dan akan ditangani oleh metode kustom.

Pemetaan HTTP:

  • Metode Update standar harus mendukung update resource parsial, dan menggunakan kata kerja HTTP PATCH dengan kolom FieldMask bernama update_mask. Kolom output yang disediakan oleh klien sebagai input harus diabaikan.
  • Metode Update yang memerlukan semantik patching yang lebih canggih, seperti menambahkan ke kolom berulang, harus disediakan dengan metode kustom.
  • Jika metode Update hanya mendukung update resource lengkap, metode tersebut harus menggunakan HTTP verb PUT. Namun, update lengkap sangat tidak dianjurkan karena memiliki masalah kompatibilitas mundur saat menambahkan kolom resource baru.
  • Kolom pesan yang menerima nama resource harus dipetakan ke jalur URL. Kolom mungkin ada dalam pesan resource itu sendiri.
  • Kolom pesan permintaan yang berisi resource harus dipetakan ke isi permintaan.
  • Semua kolom pesan permintaan yang tersisa harus dipetakan ke parameter kueri URL.
  • Pesan respons harus berupa resource yang diperbarui itu sendiri.

Jika API menerima nama resource yang ditetapkan klien, server dapat mengizinkan klien untuk menetapkan nama resource yang tidak ada dan membuat resource baru. Jika tidak, metode Update akan gagal dengan nama resource yang tidak ada. Kode error NOT_FOUND harus digunakan jika merupakan satu-satunya kondisi error.

API dengan metode Update yang mendukung pembuatan resource juga harus menyediakan metode Create. Alasannya adalah tidak jelas cara membuat resource jika metode Update adalah satu-satunya cara untuk melakukannya.

Contoh:

// Updates a book.
rpc UpdateBook(UpdateBookRequest) returns (Book) {
  // Update maps to HTTP PATCH. Resource name is mapped to a URL path.
  // Resource is contained in the HTTP request body.
  option (google.api.http) = {
    // Note the URL template variable which captures the resource name of the
    // book to update.
    patch: "/v1/{book.name=shelves/*/books/*}"
    body: "book"
  };
}

message UpdateBookRequest {
  // The book resource which replaces the resource on the server.
  Book book = 1;

  // The update mask applies to the resource. For the `FieldMask` definition,
  // see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask
  FieldMask update_mask = 2;
}

Hapus

Metode Delete mengambil nama resource serta nol atau beberapa parameter, serta menghapus atau menjadwalkan penghapusan resource yang ditentukan. Metode Delete harus menampilkan google.protobuf.Empty.

API tidak boleh mengandalkan informasi yang ditampilkan oleh metode Delete, karena tidak dapat dipanggil berulang kali.

Pemetaan HTTP:

  • Metode Delete harus menggunakan kata kerja DELETE HTTP.
  • Kolom pesan permintaan yang menerima nama resource harus dipetakan ke jalur URL.
  • Semua kolom pesan permintaan yang tersisa akan dipetakan ke parameter kueri URL.
  • Tidak ada isi permintaan; konfigurasi API tidak boleh mendeklarasikan klausa body.
  • Jika metode Delete langsung menghapus resource, metode tersebut seharusnya menampilkan respons kosong.
  • Jika metode Delete memulai operasi yang berjalan lama, metode tersebut harus menampilkan operasi yang berjalan lama.
  • Jika metode Delete hanya menandai resource sebagai dihapus, metode tersebut seharusnya menampilkan resource yang diupdate.

Panggilan ke metode Delete harus idempoten, tetapi tidak perlu menghasilkan respons yang sama. Sejumlah permintaan Delete akan mengakibatkan resource (akhirnya) dihapus, tetapi hanya permintaan pertama yang akan menghasilkan kode yang berhasil. Permintaan berikutnya akan menghasilkan google.rpc.Code.NOT_FOUND.

Contoh:

// Deletes a book.
rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {
  // Delete maps to HTTP DELETE. Resource name maps to the URL path.
  // There is no request body.
  option (google.api.http) = {
    // Note the URL template variable capturing the multi-segment name of the
    // book resource to be deleted, such as "shelves/shelf1/books/book2"
    delete: "/v1/{name=shelves/*/books/*}"
  };
}

message DeleteBookRequest {
  // The resource name of the book to be deleted, for example:
  // "shelves/shelf1/books/book2"
  string name = 1;
}
Sebelumnya
Nama resource
Berikutnya
Metode kustom