Konvensi penamaan

Untuk memberikan pengalaman developer yang konsisten di banyak API dan selama jangka waktu yang lama, semua nama yang digunakan oleh API harus:

• sederhana
• intuitif
• konsisten

Hal ini mencakup nama antarmuka, resource, koleksi, metode, dan pesan.

Karena banyak developer bukan penutur asli bahasa Inggris, salah satu tujuankonvensi penamaan ini adalah untuk memastikan bahwa sebagian besar developer dapat memahami API dengan mudah. Hal ini dilakukan dengan mendorong penggunaan kosakata yang sederhana, konsisten, dan kecil saat memberi nama metode dan resource.

• Nama yang digunakan dalam API harus menggunakan bahasa Inggris Amerika yang benar. Misalnya, lisensi (bukan lisensi), warna (bukan warna).
• Bentuk singkat atau singkatan kata panjang yang umum diterima dapat digunakan untuk mempersingkat. Misalnya, API lebih disukai daripada Application Programming Interface.
• Gunakan terminologi yang intuitif dan sudah dikenal jika memungkinkan. Misalnya, saat menjelaskan penghapusan (dan pemusnahan) resource, penghapusan lebih disukai daripada penghapusan total.
• Gunakan nama atau istilah yang sama untuk konsep yang sama, termasuk untuk konsep yang dibagikan di seluruh API.
• Hindari kelebihan nama. Gunakan nama yang berbeda untuk konsep yang berbeda.
• Hindari nama yang terlalu umum dan ambigu dalam konteks API dan ekosistem Google API yang lebih besar. Hal ini dapat menyebabkan kesalahpahaman tentang konsep API. Sebagai gantinya, pilih nama spesifik yang menjelaskan konsep API secara akurat. Hal ini sangat penting untuk nama yang menentukan elemen API tingkat pertama, seperti resource. Tidak ada daftar nama yang pasti untuk dihindari, karena setiap nama harus dievaluasi dalam konteks nama lain. Instance, info, dan layanan adalah contoh nama yang pernah bermasalah di masa lalu. Nama yang dipilih harus menjelaskan konsep API dengan jelas (misalnya: instance dari apa?) dan membedakannya dari konsep relevan lainnya (misalnya: apakah "alert" berarti aturan, sinyal, atau notifikasi?).
• Pertimbangkan dengan cermat penggunaan nama yang mungkin bertentangan dengan kata kunci dalam bahasa pemrograman umum. Nama tersebut dapat digunakan, tetapi kemungkinan akan memicu pemeriksaan tambahan selama peninjauan API. Gunakan dengan wisely dan seperlunya.

Nama produk

Nama produk mengacu pada nama pemasaran produk API, seperti Google Calendar API. Nama produk harus digunakan secara konsisten oleh API, UI, dokumentasi, Persyaratan Layanan, laporan penagihan, kontrak komersial, dll. Google API harus menggunakan nama produk yang disetujui oleh tim produk dan pemasaran.

Tabel di bawah menunjukkan contoh semua nama API terkait dan konsistensinya. Lihat di bawah ini di halaman ini untuk mengetahui detail selengkapnya tentang nama masing-masing dan konvensinya.

Nama API	Contoh
Nama Produk	Google Calendar API
Nama Layanan	calendar.googleapis.com
Nama Paket	google.calendar.v3
Nama Antarmuka	google.calendar.v3.CalendarService
Direktori Sumber	//google/calendar/v3
Nama API	calendar

Nama layanan

Nama layanan harus berupa nama DNS yang valid secara sintaksis (sesuai dengan RFC 1035) yang dapat di-resolve ke satu atau beberapa alamat jaringan. Nama layanan Google API publik mengikuti pola: xxx.googleapis.com. Misalnya, nama layanan Google Kalender adalah calendar.googleapis.com.

Jika API terdiri dari beberapa layanan, layanan tersebut harus diberi nama dengan cara yang membantu visibilitas. Salah satu cara untuk melakukannya adalah dengan Nama Layanan berbagi awalan yang sama. Misalnya, layanan build.googleapis.com dan buildresults.googleapis.com adalah layanan yang merupakan bagian dari Google Build API.

Nama paket

Nama paket yang dideklarasikan dalam file .proto API harus konsisten dengan Nama Produk dan Nama Layanan. Nama paket harus menggunakan nama komponen tunggal untuk menghindari nama komponen tunggal dan jamak yang tercampur. Nama paket tidak boleh menggunakan garis bawah. Nama paket untuk API berversi harus diakhiri dengan versi. Contoh:

// Google Calendar API
package google.calendar.v3;

API abstrak yang tidak terkait langsung dengan layanan, seperti Google Watcher API, harus menggunakan nama paket proto yang konsisten dengan nama Produk:

// Google Watcher API
package google.watcher.v1;

Nama paket Java yang ditentukan dalam file .proto API harus cocok dengan nama paket proto dengan awalan nama paket Java standar (com., edu., net., dll.). Contoh:

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

ID koleksi

ID koleksi harus menggunakan bentuk jamak dan lowerCamelCase, serta ejaan dan semantik bahasa Inggris Amerika. Misalnya: events, children, atau deletedEvents.

Nama antarmuka

Untuk menghindari kebingungan dengan Nama Layanan seperti pubsub.googleapis.com, istilah nama antarmuka mengacu pada nama yang digunakan saat menentukan service dalam file .proto:

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

Anda dapat menganggap nama layanan sebagai referensi untuk implementasi sebenarnya dari serangkaian API, sedangkan nama antarmuka mengacu pada definisi abstrak API.

Nama antarmuka harus menggunakan kata benda intuitif seperti Kalender atau Blob. Nama tidak boleh bertentangan dengan konsep yang sudah mapan dalam bahasa pemrograman dan library runtime-nya (misalnya, File).

Dalam kasus yang jarang terjadi, jika nama antarmuka akan bertentangan dengan nama lain dalam API, akhiran (misalnya Api atau Service) harus digunakan untuk membedakan.

Nama metode

Dalam spesifikasi IDL-nya, layanan dapat menentukan satu atau beberapa metode RPC yang sesuai dengan metode pada koleksi dan resource. Nama metode harus mengikuti konvensi penamaan VerbNoun dalam camel case besar, dengan kata benda biasanya adalah jenis resource.

Kata kerja	Kata benda	Nama metode	Pesan permintaan	Pesan respons
List	Book	ListBooks	ListBooksRequest	ListBooksResponse
Get	Book	GetBook	GetBookRequest	Book
Create	Book	CreateBook	CreateBookRequest	Book
Update	Book	UpdateBook	UpdateBookRequest	Book
Rename	Book	RenameBook	RenameBookRequest	RenameBookResponse
Delete	Book	DeleteBook	DeleteBookRequest	google.protobuf.Empty

Bagian kata kerja dari nama metode harus menggunakan modus imperatif, yang digunakan untuk perintah atau perintah, bukan modus indikatif yang digunakan untuk pertanyaan.

Untuk metode standar, bagian kata benda dari nama metode harus tunggal untuk semua metode kecuali List, dan harus jamak untuk List. Untuk metode kustom, kata benda dapat berupa tunggal atau jamak sesuai kebutuhan. Metode batch harus menggunakan kata benda jamak.

Catatan: Kasus di atas merujuk pada nama RPC dalam buffering protokol; akhiran URI HTTP/JSON menggunakan :lowerCamelCase.

Hal ini mudah membingungkan saat kata kerja mengajukan pertanyaan tentang sub-resource di API, yang sering kali dinyatakan dalam mood indikatif. Misalnya, memerintahkan API untuk membuat buku jelas-jelas CreateBook (dalam mood imperatif), tetapi menanyakan API tentang status penerbit buku mungkin menggunakan mood indikatif, seperti IsBookPublisherApproved atau NeedsPublisherApproval. Agar tetap dalam mood imperatif dalam situasi seperti ini, gunakan perintah seperti "check" (CheckBookPublisherApproved) dan "validate" (ValidateBookPublisher).

Nama metode tidak boleh menyertakan preposisi (misalnya, "For", "With", "At", "To"). Secara umum, nama metode dengan preposisi menunjukkan bahwa metode baru digunakan saat kolom harus ditambahkan ke metode yang ada, atau metode harus menggunakan kata kerja yang berbeda.

Misalnya, jika pesan CreateBook sudah ada dan Anda mempertimbangkan untuk menambahkan CreateBookFromDictation, sebaiknya pertimbangkan metode TranscribeBook.

Nama pesan

Nama pesan harus singkat dan ringkas. Hindari kata-kata yang tidak perlu atau berlebihan. Kata sifat sering kali dapat dihilangkan jika tidak ada pesan yang sesuai tanpa kata sifat. Misalnya, Shared di SharedProxySettings tidak diperlukan jika tidak ada setelan proxy yang tidak dibagikan.

Nama pesan tidak boleh menyertakan preposisi (misalnya, "Dengan", "Untuk"). Umumnya, nama pesan dengan preposisi lebih baik direpresentasikan dengan kolom opsional pada pesan.

Pesan permintaan dan respons

Pesan permintaan dan respons untuk metode RPC harus diberi nama setelah nama metode dengan akhiran Request dan Response, masing-masing, kecuali jika jenis permintaan atau respons metode adalah:

• pesan kosong (gunakan google.protobuf.Empty),
• jenis resource, atau
• resource yang mewakili operasi

Hal ini biasanya berlaku untuk permintaan atau respons yang digunakan dalam metode standar Get, Create, Update, atau Delete.

Nama enum

Jenis enum harus menggunakan nama UpperCamelCase.

Nilai enum harus menggunakan CAPITALIZED_NAMES_WITH_UNDERSCORES. Setiap nilai enum harus diakhiri dengan titik koma, bukan koma. Nilai pertama harus diberi nama ENUM_TYPE_UNSPECIFIED karena ditampilkan saat nilai enum tidak ditentukan secara eksplisit.

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

Wrapper

Pesan yang mengenkapsulasi jenis enum proto2 dengan nilai 0 yang memiliki makna selain UNSPECIFIED harus diberi nama dengan akhiran Value dan memiliki satu kolom bernama value.

enum OldEnum {
  VALID = 0;
  OTHER_VALID = 1;
}
message OldEnumValue {
  OldEnum value = 1;
}

Nama kolom

Definisi kolom dalam file .proto harus menggunakan nama_yang_dipisahkan_underscore_huruf_kecil. Nama ini akan dipetakan ke konvensi penamaan native dalam kode yang dihasilkan untuk setiap bahasa pemrograman.

Nama kolom tidak boleh menyertakan preposisi (misalnya, "for", "during", "at"), misalnya:

• reason_for_error harus error_reason
• cpu_usage_at_time_of_failure harus failure_time_cpu_usage

Nama kolom tidak boleh menggunakan kata sifat postpositif (pengubah yang ditempatkan setelah kata benda), misalnya:

• items_collected harus collected_items
• objects_imported harus imported_objects

Nama kolom berulang

Kolom berulang di API harus menggunakan bentuk jamak yang tepat. Hal ini sesuai dengankonvensi Google API yang ada, dan ekspektasi umum dari developer eksternal.

Waktu dan Durasi

Untuk merepresentasikan titik waktu yang tidak bergantung pada zona waktu atau kalender apa pun, google.protobuf.Timestamp harus digunakan, dan nama kolom harus diakhiri dengan time, seperti start_time dan end_time.

Jika waktu mengacu pada aktivitas, nama kolom harus memiliki bentuk verb_time, seperti create_time, update_time. Hindari penggunaan bentuk lampau untuk kata kerja, seperti created_time atau last_updated_time.

Untuk merepresentasikan rentang waktu antara dua titik waktu yang tidak bergantung pada kalender dan konsep apa pun seperti "hari" atau "bulan", google.protobuf.Duration harus digunakan.

message FlightRecord {
  google.protobuf.Timestamp takeoff_time = 1;
  google.protobuf.Duration flight_duration = 2;
}

Jika Anda harus merepresentasikan kolom terkait waktu menggunakan jenis bilangan bulat karena alasan kompatibilitas atau lama, termasuk waktu jam dinding, durasi, keterlambatan, dan latensi, nama kolom harus memiliki bentuk berikut:

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}

message Email {
  int64 send_time_millis = 1;
  int64 receive_time_millis = 2;
}

Jika Anda harus menampilkan stempel waktu menggunakan jenis string karena alasan kompatibilitas atau lama, nama kolom tidak boleh menyertakan akhiran unit apa pun. Representasi string harus menggunakan format RFC 3339, misalnya "2014-07-30T10:43:17Z".

Tanggal dan Waktu

Untuk tanggal yang tidak bergantung pada zona waktu dan waktu, google.type.Date harus digunakan dan harus memiliki akhiran _date. Jika tanggal harus direpresentasikan sebagai string, tanggal harus dalam format tanggal ISO 8601 YYYY-MM-DD, misalnya 2014-07-30.

Untuk waktu yang tidak bergantung pada zona waktu dan tanggal, google.type.TimeOfDay harus digunakan dan harus memiliki akhiran _time. Jika waktu harus direpresentasikan sebagai string, waktu tersebut harus dalam format waktu 24 jam ISO 8601 HH:MM:SS[.FFF], misalnya 14:55:01.672.

message StoreOpening {
  google.type.Date opening_date = 1;
  google.type.TimeOfDay opening_time = 2;
}

Jumlah

Jumlah yang direpresentasikan oleh jenis bilangan bulat harus menyertakan satuan pengukuran.

xxx_{bytes|width_pixels|meters}

Jika kuantitas adalah jumlah item, kolom harus memiliki akhiran _count, misalnya node_count.

Kolom filter daftar

Jika API mendukung pemfilteran resource yang ditampilkan oleh metode List, kolom yang berisi ekspresi filter harus diberi nama filter. Contoh:

message ListBooksRequest {
  // The parent resource name.
  string parent = 1;

  // The filter expression.
  string filter = 2;
}

Respons daftar

Nama kolom dalam pesan respons metode List, yang berisi daftar resource harus berupa bentuk jamak dari nama resource itu sendiri. Misalnya, metode CalendarApi.ListEvents() harus menentukan pesan respons ListEventsResponse dengan kolom berulang yang disebut events untuk daftar resource yang ditampilkan.

service CalendarApi {
  rpc ListEvents(ListEventsRequest) returns (ListEventsResponse) {
    option (google.api.http) = {
      get: "/v3/{parent=calendars/*}/events";
    };
  }
}

message ListEventsRequest {
  string parent = 1;
  int32 page_size = 2;
  string page_token = 3;
}

message ListEventsResponse {
  repeated Event events = 1;
  string next_page_token = 2;
}

Camel case

Kecuali untuk nama kolom dan nilai enum, semua definisi di dalam file .proto harus menggunakan nama UpperCamelCase, seperti yang ditentukan oleh Gaya Java Google.

Singkatan nama

Untuk singkatan nama yang dikenal luas di kalangan developer software, seperti config dan spec, singkatan harus digunakan dalam definisi API, bukan ejaan lengkapnya. Hal ini akan membuat kode sumber mudah dibaca dan ditulis. Dalam dokumentasi formal, ejaan lengkap harus digunakan. Contoh:

• config (konfigurasi)
• id (ID)
• spec (spesifikasi)
• stats (statistik)