Changelog

Introduction

This is a general design guide for networked APIs. It has been used insideGoogle since 2014 and is the guide that Google follows when designingCloud APIs and otherGoogle APIs.This design guide is shared here to inform outside developers and to make iteasier for us all to work together.

Cloud Endpoints developers may find thisguide particularly useful when designing gRPC APIs, and we strongly recommendsuch developers use these design principles. However,we don't mandate its use. You can use CloudEndpoints and gRPC without following the guide.

This guide applies to both REST APIs and RPC APIs, with specific focus on gRPCAPIs. gRPC APIs useProtocol Buffers to define their API surfaceandAPI Service Configuration to configure their API services, includingHTTP mapping, logging, and monitoring. HTTP mapping features are used by GoogleAPIs and Cloud Endpoints gRPC APIs for JSON/HTTP to Protocol Buffers/RPCtranscoding.

This guide is a living document and additions to it will be madeover time as new style and design patterns are adopted and approved. In thatspirit, it is never going to be complete and there will always be ampleroom for the art and craft of API design.

Conventions Used in This Guide

The requirement level keywords "MUST", "MUST NOT", "REQUIRED", "SHALL","SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and"OPTIONAL" used in this document are to be interpreted as described inRFC 2119.

In this document, such keywords are highlighted usingbold font.

Sections

Resource-oriented Design

For information about implementing resource-oriented design forRPC and REST APIs, seeAIP-121.

Resource Names

For information about resource names,seeAIP-122.

Standard Methods

For general information about methods, seeAIP-130.

For information about standard methods, see the following AIPs:

• ForGet, seeAIP-131
• ForList, seeAIP-132
• ForCreate, seeAIP-133
• ForUpdate, seeAIP-134
• ForDelete, seeAIP-135

Custom Methods

For information about custom methods, seeAIP-136.

Additional topics

For information about the following topics, see their related AIPs.

• ForStandard fields, seeAIP-148
• ForErrors, seeAIP-193
• ForDesign patterns, seeAIP guidance on design patterns
• ForInline API documentation, seeAIP-192
• ForUsing proto3, seethe Syntax section of AIP-191
• ForVersioning, seeAIP-185
• ForBackward compatibility, seeAIP-180
• ForFile structure, seethe File Layout section of AIP-191
• For aGlossary of terms, seeAIP-9
• ForNaming conventions, seeAIP-190

For information about the following topics, see their related pages in this guide.

• Directory Structure