Konvensi penamaan

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

  • sederhana
  • intuitif.
  • konsisten

Ini termasuk nama antarmuka, resource, koleksi, metode, dan pesan.

Karena banyak developer bukan penutur asli bahasa Inggris, salah satu tujuan konvensi 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 menamai metode dan sumber daya.

  • Nama yang digunakan dalam API harus dalam bahasa Inggris Amerika yang benar. Misalnya, lisensi (bukan lisensi), warna (bukan warna).
  • Bentuk pendek atau singkatan dari kata panjang yang diterima secara umum dapat digunakan agar lebih singkat. Misalnya, API lebih diprioritaskan daripada Application Programming Interface.
  • Gunakan terminologi yang intuitif dan familier jika memungkinkan. Misalnya, saat menjelaskan penghapusan (dan penghancuran) resource, opsi hapus lebih diutamakan daripada penghapusan.
  • 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. Sebaliknya, pilih nama spesifik yang menjelaskan konsep API secara akurat. Hal ini sangat penting untuk nama yang menentukan elemen API urutan pertama, seperti resource. Tidak ada daftar nama definitif yang harus 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 mendeskripsikan konsep API dengan jelas (misalnya: instance apa?) dan membedakannya dari konsep lainnya yang relevan (misalnya: apakah "pemberitahuan" berarti aturan, sinyal, atau notifikasi?).
  • Pertimbangkan 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 keduanya dengan bijak dan hemat.

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 tagihan, kontrak komersial, dll. Google API harus menggunakan nama produk yang disetujui oleh tim produk dan pemasaran.

Tabel di bawah ini menunjukkan contoh semua nama API terkait dan konsistensinya. Lihat lebih lanjut di bagian bawah halaman ini untuk mengetahui detail selengkapnya tentang masing-masing nama 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 RFC 1035) yang dapat di-resolve menjadi 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, API tersebut harus diberi nama agar lebih mudah ditemukan. Salah satu cara untuk melakukannya adalah agar Nama Layanan memiliki 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 campuran nama komponen tunggal dan jamak. 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 ini tidak boleh bertentangan dengan konsep yang sudah ditetapkan dalam bahasa pemrograman dan library runtime-nya (misalnya, File).

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

Nama metode

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

Kata Kerja Noun 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 mood imperatif, yang ditujukan untuk urutan atau perintah, bukan mood indikatif untuk pertanyaan.

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

Hal ini mudah membingungkan saat kata kerja mengajukan pertanyaan tentang sub-resource di API, yang sering dinyatakan dalam mood indikatif. Misalnya, meminta API untuk membuat buku jelas adalah CreateBook (dalam suasana wajib), tetapi menanyakan status penerbit buku mungkin akan menggunakan mood indikatif, seperti IsBookPublisherApproved atau NeedsPublisherApproval. Agar tetap dalam suasana imperatif dalam situasi seperti ini, andalkan perintah seperti "periksa" (CheckBookPublisherApproved) dan "validasi" (ValidateBookPublisher).

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

Misalnya, jika pesan CreateBook sudah ada dan Anda mempertimbangkan untuk menambahkan CreateBookFromDictation, 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 yang memiliki preposisi akan lebih baik direpresentasikan dengan kolom opsional pada pesan.

Pesan permintaan dan respons

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

  • pesan kosong (gunakan google.protobuf.Empty),
  • tipe sumber daya, 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;
}

Pembungkus

Pesan yang mengenkapsulasi jenis enum proto2 yang nilai 0-nya memiliki arti 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 di file .proto harus menggunakan lower_case_underscore_separated_names. Nama-nama ini akan dipetakan ke konvensi penamaan native dalam kode yang dihasilkan untuk setiap bahasa pemrograman.

Nama kolom tidak boleh menyertakan preposisi (misalnya, "for", "between", "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 dalam API harus menggunakan bentuk jamak yang tepat. Hal ini sesuai dengan konvensi Google API yang ada, dan ekspektasi umum developer eksternal.

Waktu dan Durasi

Untuk mewakili titik waktu yang terpisah dari 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 merujuk ke aktivitas, nama kolom harus memiliki bentuk verb_time, seperti create_time, update_time. Hindari penggunaan kata kerja masa lalu, 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 integer untuk alasan lama atau kompatibilitas, termasuk waktu wall-clock, durasi, keterlambatan, dan latensi, nama kolom harus memiliki format 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 merepresentasikan stempel waktu menggunakan jenis string karena alasan lama atau kompatibilitas, 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 akhiran _date harus digunakan. Jika harus direpresentasikan sebagai string, tanggal tersebut 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;
}

Kuantitas

Jumlah yang diwakili oleh jenis bilangan bulat harus menyertakan unit pengukuran.

xxx_{bytes|width_pixels|meters}

Jika jumlahnya berupa sejumlah 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 ListEventsResponse pesan respons 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;
}

{i>Camel case<i}

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

Singkatan nama

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

  • konfigurasi (konfigurasi)
  • id (pengenal)
  • spesifikasi (spesifikasi)
  • statistik (statistik)
Sebelumnya
Error
Berikutnya
Pola desain