API Improvement Proposals

Google maintains a set of documents called API Improvement Proposals (AIPs) that lay out conventions and best practices that they follow internally when designing APIs. Below are a few proposals I find particularly enlightening for establishing strong conventions.

AIP-121: Resource-oriented design

Stateless, REST-like focus on interacting with resources via well-defined verbs (HTTP methods) when possible. Allows for custom methods when necessary.

Having an API that is identical to the underlying database schema is actually an anti-pattern, as it tightly couples the surface to the underlying system.

AIP-122: Resource names

Naming conventions for resources: plural, camelCase. Paths should tend to alternate between collections and specific IDs (such as /books/123/pages/14). Nested collection names can omit common prefixes, as in accessing a list of ProjectUsers via /projects/1/users.

Includes some Google-specific cross-API conventions.

AIP-124: Resource association

Conventions around resources with multiple many-to-one and many-to-many relationships.

AIP-126: Enumerations

UPPER_SNAKE_CASE formatting, should include an UNSPECIFIED or UNKNOWN case (Google suggests {ENUM_NAME}_UNSPECIFIED). Enumerations should not be used when the values change frequently or when using a standard convention like language codes.

AIP-127: HTTP and gRPC Transcoding

Important because it appears that Google APIs are implemented as RPCs first, and then adapted to HTTP APIs via gRPC Transcoding.

AIP-131 to AIP-135: Standard methods

REST-like resource methods that correspond with GET (single and list), POST, PUT, and DELETE.