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:
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Sulit dipahami","hardToUnderstand","thumb-down"],["Informasi atau kode contoh salah","incorrectInformationOrSampleCode","thumb-down"],["Informasi/contoh yang saya butuhkan tidak ada","missingTheInformationSamplesINeed","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 2025-09-04 UTC."],[[["\u003cp\u003eThis guide outlines Google's API design principles, used internally since 2014, and applicable to both REST and RPC APIs with a focus on gRPC.\u003c/p\u003e\n"],["\u003cp\u003eCloud Endpoints developers using gRPC APIs may find this guide particularly useful, although its use is not mandatory.\u003c/p\u003e\n"],["\u003cp\u003eThe guide covers various topics including resource-oriented design, standard methods, custom methods, standard fields, errors, design patterns, versioning, and more, referencing external links and AIPs.\u003c/p\u003e\n"],["\u003cp\u003eThis is a dynamic document that will be updated with new style and design patterns, but it will never be considered complete.\u003c/p\u003e\n"],["\u003cp\u003eKeywords like "MUST" and "SHOULD" are used with specific meanings as per RFC 2119, and are highlighted in \u003cstrong\u003ebold\u003c/strong\u003e within the guide.\u003c/p\u003e\n"]]],[],null,["# API design guide\n\n[Changelog](https://cloud.google.com/apis/design/changelog)\n\nIntroduction\n------------\n\nThis is a general design guide for networked APIs. It has been used inside\nGoogle since 2014 and is the guide that Google follows when designing\n[Cloud APIs](/apis/docs/overview) and other\n[Google APIs](https://github.com/googleapis/googleapis).\nThis design guide is shared here to inform outside developers and to make it\neasier for us all to work together.\n\n[Cloud Endpoints](/endpoints/docs/grpc) developers may find this\nguide particularly useful when designing gRPC APIs, and we strongly recommend\nsuch developers use these design principles. However,\nwe don't mandate its use. You can use Cloud\nEndpoints and gRPC without following the guide.\n\nThis guide applies to both REST APIs and RPC APIs, with specific focus on gRPC\nAPIs. gRPC APIs use [Protocol Buffers](/apis/design/proto3) to define their API surface\nand [API Service Configuration](https://github.com/googleapis/googleapis/blob/master/google/api/service.proto) to configure their API services, including\nHTTP mapping, logging, and monitoring. HTTP mapping features are used by Google\nAPIs and Cloud Endpoints gRPC APIs for JSON/HTTP to Protocol Buffers/RPC\n[transcoding](/endpoints/docs/transcoding).\n\nThis guide is a living document and additions to it will be made\nover time as new style and design patterns are adopted and approved. In that\nspirit, it is never going to be complete and there will always be ample\nroom for the art and craft of API design.\n\nConventions Used in This Guide\n------------------------------\n\nThe requirement level keywords \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\",\n\"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and\n\"OPTIONAL\" used in this document are to be interpreted as described in\n[RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).\n\nIn this document, such keywords are highlighted using **bold** font.\n\nSections\n--------\n\n### Resource-oriented Design\n\nFor information about implementing resource-oriented design for\nRPC and REST APIs, see [AIP-121](https://google.aip.dev/121).\n\n### Resource Names\n\nFor information about resource names,\nsee [AIP-122](https://google.aip.dev/122).\n\n### Standard Methods\n\nFor general information about methods, see [AIP-130](https://google.aip.dev/130).\n\nFor information about standard methods, see the following AIPs:\n\n- For `Get`, see [AIP-131](https://google.aip.dev/131)\n- For `List`, see [AIP-132](https://google.aip.dev/132)\n- For `Create`, see [AIP-133](https://google.aip.dev/133)\n- For `Update`, see [AIP-134](https://google.aip.dev/134)\n- For `Delete`, see [AIP-135](https://google.aip.dev/135)\n\n### Custom Methods\n\nFor information about custom methods, see [AIP-136](https://google.aip.dev/136).\n\n### Additional topics\n\nFor information about the following topics, see their related AIPs.\n\n- For **Standard fields** , see [AIP-148](https://google.aip.dev/148)\n- For **Errors** , see [AIP-193](https://google.aip.dev/193)\n- For **Design patterns** , see [AIP guidance on design patterns](https://google.aip.dev/general#design-patterns)\n- For **Inline API documentation** , see [AIP-192](https://google.aip.dev/192)\n- For **Using proto3** , see [the Syntax section of AIP-191](https://google.aip.dev/191#syntax)\n- For **Versioning** , see [AIP-185](https://google.aip.dev/185)\n- For **Backward compatibility** , see [AIP-180](https://google.aip.dev/180)\n- For **File structure** , see [the File Layout section of AIP-191](https://google.aip.dev/191#file-layout)\n- For a **Glossary** of terms, see [AIP-9](https://google.aip.dev/9)\n- For **Naming conventions** , see [AIP-190](https://google.aip.dev/190)\n\nFor information about the following topics, see their related pages in this guide.\n\n- [Directory Structure](https://cloud.google.com/apis/design/directory_structure)"]]
