Nama resource

Dalam API berorientasi resource, resource adalah entity bernama, dan nama resource adalah IDnya. Setiap resource harus memiliki nama resource uniknya sendiri. Nama resource terdiri dari ID resource itu sendiri, ID resource induk, dan nama layanan API-nya. Kita akan melihat ID resource dan cara nama resource dibuat di bawah.

gRPC API harus menggunakan URI tanpa skema untuk nama resource. Library ini umumnya mengikuti konvensi URL REST dan berperilaku seperti jalur file jaringan. Metode ini dapat dengan mudah dipetakan ke URL REST: lihat bagian Metode Standar untuk mengetahui detailnya.

Koleksi adalah jenis resource khusus yang berisi daftar sub-resource dengan jenis identik. Misalnya, direktori adalah kumpulan resource file. ID resource untuk koleksi disebut ID koleksi.

Nama resource diatur secara hierarkis menggunakan ID koleksi dan ID resource, yang dipisahkan dengan garis miring ke depan. Jika resource berisi sub-resource, nama sub-resource akan dibuat dengan menentukan nama resource induk diikuti dengan ID sub-resource - sekali lagi, yang dipisahkan dengan garis miring ke depan.

Contoh 1: Layanan penyimpanan memiliki kumpulan buckets, yang setiap bucket memiliki kumpulan objects:

Nama Layanan API	ID Koleksi	ID aset	ID Koleksi	ID aset
//storage.googleapis.com	/buckets	/bucket-id	/objects	/object-id

Contoh 2: Layanan email memiliki kumpulan users. Setiap pengguna memiliki sub-resource settings, dan sub-resource settings memiliki sejumlah sub-resource lain, termasuk customFrom:

Nama Layanan API	ID Koleksi	ID aset	ID aset	ID aset
//mail.googleapis.com	/users	/[e-mail]	/settings	/customFrom

Produsen API dapat memilih nilai yang dapat diterima untuk ID resource dan koleksi selama ID tersebut unik dalam hierarki resource. Anda dapat menemukan panduan selengkapnya terkait cara memilih resource dan ID koleksi yang sesuai di bawah ini.

Dengan memisahkan nama resource, seperti name.split("/")[n], seseorang bisa mendapatkan ID koleksi individual dan ID resource, dengan asumsi tidak ada segmen yang berisi garis miring.

Nama Lengkap Resource

URI tanpa skema yang terdiri dari nama layanan API yang kompatibel dengan DNS dan jalur resource. Jalur resource juga disebut sebagai nama resource relatif. Contoh:

"//library.googleapis.com/shelves/shelf1/books/book2"

Nama layanan API ditujukan bagi klien untuk menemukan endpoint layanan API; nama tersebut mungkin berupa nama DNS palsu untuk layanan khusus internal. Jika nama layanan API terlihat jelas dari konteksnya, nama resource relatif sering digunakan.

Nama Resource Relatif

Jalur URI (path-noskema) tanpa awalan "/". Jalur ini mengidentifikasi resource dalam layanan API. Contoh:

"shelves/shelf1/books/book2"

ID aset

ID resource biasanya terdiri dari satu atau beberapa segmen URI yang tidak kosong (segment-nz-nc) yang mengidentifikasi resource dalam resource induknya, lihat contoh di atas. ID resource bukan akhir dalam nama resource harus memiliki tepat satu segmen URL, sedangkan ID resource akhir dalam nama resource dapat memiliki lebih dari satu segmen URI. Contoh:

ID Koleksi	ID aset
file	source/py/parser.py

Layanan API harus menggunakan ID resource yang cocok untuk URL jika memungkinkan. ID resource harus didokumentasikan dengan jelas, baik diberikan oleh klien, server, atau keduanya. Misalnya, nama file biasanya ditetapkan oleh klien, sedangkan ID pesan email biasanya ditetapkan oleh server.

ID Koleksi

Segmen URI yang tidak kosong (segment-nz-nc) yang mengidentifikasi resource koleksi dalam resource induknya, lihat contoh di atas.

Karena ID koleksi sering muncul di library klien yang dihasilkan, ID tersebut harus mematuhi persyaratan berikut:

• Harus berupa ID C/C++ yang valid.
• Harus dalam bentuk jamak dengan huruf kecil Camel. Jika istilah tersebut tidak memiliki bentuk jamak yang sesuai, seperti "bukti" dan "cuaca", bentuk tunggal harus digunakan.
• Harus menggunakan istilah bahasa Inggris yang jelas dan ringkas.
• Istilah yang terlalu umum harus dihindari atau memenuhi syarat. Misalnya, rowValues lebih disukai daripada values. Persyaratan berikut harus dihindari tanpa kualifikasi:
  • elemen
  • entri
  • instance
  • item
  • objek
  • resource
  • jenis
  • nilai

Nama Resource vs URL

Meskipun nama resource lengkap menyerupai URL biasa, nama resource tidak sama. Satu resource dapat diekspos oleh versi API, protokol API, atau endpoint jaringan API yang berbeda. Nama lengkap resource tidak menentukan informasi tersebut, sehingga harus dipetakan ke versi API dan protokol API tertentu untuk penggunaan sebenarnya.

Untuk menggunakan nama lengkap resource melalui REST API, resource tersebut harus dikonversi ke URL REST dengan menambahkan skema HTTPS sebelum nama layanan, menambahkan versi utama API sebelum jalur resource, dan meng-escape URL jalur resource. Contoh:

// This is a calendar event resource name.
"//calendar.googleapis.com/users/john smith/events/123"

// This is the corresponding HTTP URL.
"https://calendar.googleapis.com/v3/users/john%20smith/events/123"

Nama Resource sebagai String

Google API harus merepresentasikan nama resource menggunakan string biasa, kecuali jika kompatibilitas mundur menjadi masalah. Nama resource harus ditangani seperti jalur file normal. Ketika diteruskan di antara komponen yang berbeda, nama resource harus diperlakukan sebagai nilai atom dan tidak boleh kehilangan data.

Untuk definisi resource, kolom pertama harus berupa kolom string untuk nama resource, dan harus disebut name.

Catatan: Contoh kode berikut menggunakan sintaksis gRPC Transcoding. Klik link untuk melihat detailnya.

Contoh:

service LibraryService {
  rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
      get: "/v1/{name=shelves/*/books/*}"
    };
  };
  rpc CreateBook(CreateBookRequest) returns (Book) {
    option (google.api.http) = {
      post: "/v1/{parent=shelves/*}/books"
      body: "book"
    };
  };
}

message Book {
  // Resource name of the book. It must have the format of "shelves/*/books/*".
  // For example: "shelves/shelf1/books/book2".
  string name = 1;

  // ... other properties
}

message GetBookRequest {
  // Resource name of a book. For example: "shelves/shelf1/books/book2".
  string name = 1;
}

message CreateBookRequest {
  // Resource name of the parent resource where to create the book.
  // For example: "shelves/shelf1".
  string parent = 1;
  // The Book resource to be created. Client must not set the `Book.name` field.
  Book book = 2;
}

Catatan: Agar nama resource konsisten, garis miring di awal tidak boleh diambil oleh variabel template URL. Misalnya, template URL "/v1/{name=shelves/*/books/*}" harus digunakan, bukan "/v1{name=/shelves/*/books/*}".

Pertanyaan

T: Mengapa tidak menggunakan ID resource untuk mengidentifikasi resource?

Untuk setiap sistem besar, terdapat banyak jenis sumber daya. Untuk menggunakan ID resource guna mengidentifikasi resource, kami sebenarnya menggunakan tuple spesifik per resource untuk mengidentifikasi resource, seperti (bucket, object) atau (user, album, photo). Hal ini menimbulkan beberapa masalah utama:

• Developer harus memahami dan mengingat tuple anonim tersebut.
• Meneruskan tuple biasanya lebih sulit daripada meneruskan string.
• Infrastruktur terpusat, seperti logging dan sistem kontrol akses, tidak memahami tuple khusus.
• Tuple khusus membatasi fleksibilitas desain API, misalnya menyediakan antarmuka API yang dapat digunakan kembali. Misalnya, Operasi yang Berjalan Lama dapat berfungsi dengan banyak antarmuka API lainnya karena menggunakan nama resource yang fleksibel.

T: Mengapa kolom nama resource disebut name, bukan id?

Kolom nama resource diberi nama berdasarkan konsep "nama" resource. Secara umum, kami merasa konsep name membingungkan bagi developer. Misalnya, apakah nama {i>file<i} benar-benar hanya nama atau jalur lengkap? Dengan mencadangkan kolom standar name, developer dipaksa untuk memilih istilah yang lebih tepat, seperti display_name atau title atau full_name.

T: Bagaimana cara membuat dan mengurai nama resource?

Nama resource berperilaku seperti jalur file. Anda dapat menggunakan printf() untuk membuat nama resource dari ID resource. Anda dapat menggunakan split() untuk mengurai nama resource menjadi ID resource. Perhatikan bahwa beberapa ID Resource akhir dapat memiliki beberapa segmen URI yang dipisahkan oleh /, seperti jalur file.