Pengantar
Ini adalah panduan desain umum untuk API jaringan. Panduan ini telah digunakan di dalam Google sejak tahun 2014 dan merupakan panduan yang diikuti Google saat mendesain Cloud API dan Google API lainnya. Panduan desain ini dibagikan di sini untuk memberi tahu developer di luar dan memudahkan kita semua untuk bekerja sama.
Developer Cloud Endpoints mungkin menemukan panduan ini sangat berguna saat mendesain gRPC API, dan sebaiknya developer tersebut menggunakan prinsip desain ini. Namun, kami tidak mewajibkan penggunaannya. Anda dapat menggunakan Cloud Endpoints dan gRPC tanpa mengikuti panduan ini.
Panduan ini berlaku untuk REST API dan RPC API, dengan fokus khusus pada gRPC API. gRPC API menggunakan Protocol Buffers untuk menentukan platform API dan Konfigurasi Layanan API untuk mengonfigurasi layanan API, termasuk pemetaan, logging, dan pemantauan HTTP. Fitur pemetaan HTTP digunakan oleh Google API dan Cloud Endpoints gRPC API untuk transcoding JSON/HTTP ke Protocol Buffers/RPC.
Panduan ini adalah dokumen yang terus diperbarui dan penambahannya akan dilakukan seiring waktu seiring gaya dan pola desain baru diadopsi dan disetujui. Dengan semangat tersebut, desain API tidak akan pernah selesai dan akan selalu ada ruang yang cukup untuk seni dan keterampilan desain API.
Konvensi yang Digunakan dalam Panduan Ini
Kata kunci tingkat persyaratan "HARUS", "TIDAK BOLEH", "DIWAJIBKAN", "HARUS", "TIDAK BOLEH", "HARUS", "TIDAK BOLEH", "DISARANKAN", "MUNGKIN", dan "OPSIONAL" yang digunakan dalam dokumen ini harus ditafsirkan seperti yang dijelaskan dalam RFC 2119.
Dalam dokumen ini, kata kunci tersebut ditandai menggunakan font tebal.
Bagian
Desain Berorientasi Resource
Untuk informasi tentang cara menerapkan desain berorientasi resource untuk RPC dan REST API, lihat AIP-121.
Nama Resource
Untuk informasi tentang nama resource, lihat AIP-122.
Metode Standar
Untuk informasi umum tentang metode, lihat AIP-130.
Untuk informasi tentang metode standar, lihat AIP berikut:
- Untuk
Get, lihat AIP-131 - Untuk
List, lihat AIP-132 - Untuk
Create, lihat AIP-133 - Untuk
Update, lihat AIP-134 - Untuk
Delete, lihat AIP-135
Metode Kustom
Untuk informasi tentang metode kustom, lihat AIP-136.
Topik tambahan
Untuk informasi tentang topik berikut, lihat AIP terkait.
- Untuk Kolom standar, lihat AIP-148
- Untuk Error, lihat AIP-193
- Untuk Pola desain, lihat Panduan AIP tentang pola desain
- Untuk dokumentasi API inline, lihat AIP-192
- Untuk Menggunakan proto3, lihat bagian Sintaksis di AIP-191
- Untuk Pembuatan versi, lihat AIP-185
- Untuk Kompatibilitas mundur, lihat AIP-180
- Untuk Struktur file, lihat bagian Tata Letak File di AIP-191
- Untuk Glosarium istilah, lihat AIP-9
Untuk informasi tentang topik berikut, lihat halaman terkait dalam panduan ini.