Pengantar
Ini adalah panduan desain umum untuk API yang terhubung ke 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 eksternal dan mempermudah kita semua bekerja sama.
Developer Cloud Endpoints mungkin merasa 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 permukaan API-nya dan Konfigurasi Layanan API untuk mengonfigurasi layanan API-nya, termasuk pemetaan HTTP, logging, dan pemantauan. Fitur pemetaan HTTP digunakan oleh Google API dan Cloud Endpoints gRPC API untuk transcoding JSON/HTTP ke Protocol Buffers/RPC.
Panduan ini adalah dokumen aktif dan penambahan akan dilakukan dari waktu ke waktu seiring dengan diadopsi dan disetujuinya gaya dan pola desain baru. Dengan demikian, API tidak akan pernah selesai dan akan selalu ada banyak ruang untuk seni dan keahlian desain API.
Konvensi yang Digunakan dalam Panduan Ini
Kata kunci tingkat persyaratan "HARUS", "TIDAK BOLEH", "WAJIB", "HARUS", "TIDAK BOLEH", "SEBAIKNYA", "SEBAIKNYA TIDAK", "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 mengetahui informasi tentang penerapan desain berorientasi resource untuk RPC dan REST API, lihat AIP-121.
Nama Resource
Untuk mengetahui informasi tentang nama resource, lihat AIP-122.
Metode Standar
Untuk mengetahui informasi umum tentang metode, lihat AIP-130.
Untuk mengetahui 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 mengetahui informasi tentang metode kustom, lihat AIP-136.
Topik tambahan
Untuk mengetahui informasi tentang topik berikut, lihat AIP terkaitnya.
- 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 AIP-191
- Untuk Pembuatan Versi, lihat AIP-185
- Untuk Kompatibilitas mundur, lihat AIP-180
- Untuk Struktur file, lihat bagian Tata Letak File AIP-191
- Untuk melihat Glosarium istilah, lihat AIP-9
- Untuk Konvensi penamaan, lihat AIP-190
Untuk informasi tentang topik berikut, lihat halaman terkaitnya dalam panduan ini.