Current Version of the API Design Guide: 2017-02-21
Introduction
This is a general design guide for networked APIs. It has been used inside Google since 2014 and is the guide we follow when designingCloud APIs and otherGoogle APIs. It is shared here to inform outside developers and to make it easier for us all to work together.
External developers may find it particularly useful when designing gRPC APIs for use with Google Cloud Endpoints, and we strongly recommend such developers use these design principles. However, we don't mandate its use for any non-Google developer and you can use Cloud Endpoints and/or gRPC without following the guide.
This guide applies to both REST APIs and RPC APIs, with specific focus on gRPC APIs. gRPC APIs use Protocol Buffers to define their API surface and API Service Configuration to configure their API services, including HTTP mapping, logging, and monitoring. HTTP mapping features are used by Google APIs and gRPC Cloud Endpoints APIs for JSON/HTTP to Protocol Buffers/RPC transcoding.
This guide is a living document and additions to it will be made over time as new style and design patterns are adopted and approved. In that spirit, it is never going to be complete and there will always be ample room for the art and craft of API design.
Conventions Used in This Document
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 using bold font.