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
haruserror_reason
cpu_usage_at_time_of_failure
harusfailure_time_cpu_usage
Nama kolom tidak boleh menggunakan kata sifat postpositif (pengubah yang ditempatkan setelah kata benda), misalnya:
items_collected
haruscollected_items
objects_imported
harusimported_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)