Google API Design Guide

This Design Guide explains how to apply REST principles to API designs independent of programming language, operating system, or network protocol. It is NOT a guide solely to creating REST APIs.

The Design Guide suggests taking the following steps when designing resource- oriented APIs

Even though adding pagination support to an existing API is purely additive from API surface perspective, it is a behavior-breaking change

This page provides more detailed explanations for the list of breaking and non-breaking changes given in the Versioning section.

If the Delete method initiates a long-running operation, it should return the long-running operation.

Cancel an outstanding operation (build, computation etc.)

(:search) Alternative to List for fetching data that does not adhere to List semantics.

Sometimes, an API needs to let a client List/Search across sub- collections.

it may be useful to allow a Get to retrieve that resource without knowing which parent collection contains it

The List method takes a collection name and zero or more parameters as input, and returns a list of resources that match the input

A collection contains a list of resources of the same type. For example, a user has a collection of contacts.

The key characteristic of a resource-oriented API is that it emphasizes resources (data model) over the methods performed on the resources (functionality)

The List method must use an HTTP GET verb.

The standard Update method should support partial resource update, and use HTTP verb PATCH

If the Update method only supports full resource update, it must use HTTP verb PUT

With the HTTP protocol, the resource names naturally map to URLs, and methods naturally map to HTTP methods POST, GET, PUT, PATCH, and DELETE.

It supports both binary and text wire formats, and works with many different wire protocols on different platforms.

To provide a consistent developer experience across APIs and reduce learning curve, API designers must use the ISO 14977 Extended Backus-Naur Form (EBNF) syntax to define such grammars

To provide a consistent developer experience across APIs and reduce learning curve, API designers must use the ISO 14977 Extended Backus-Naur Form (EBNF) syntax to define such grammars

For fields that are output only, the field attribute shall be documented.

This section provides guidelines for adding inline documentation to your API. Most APIs will also have overviews, tutorials, and higher-level reference documentation, which are outside the scope of this Design Guide.

In most cases, there's more to say than just restating the obvious

If this field is set to true, the server must not execute any side effects and only perform implementation-specific validation consistent with the full request.

some API methods cannot easily be idempotent, such as creating a resource, and there is a need to avoid unnecessary duplication

This means that the server must ignore the presence of output only fields and any indication of it.

If the Delete method only marks the resource as being deleted, it should return the updated resource.

Restore a resource that was previously deleted. The recommended retention period is 30-day.

Must use clear and concise English terms.

Names used in APIs should be in correct American English.

Must be in plural form with lowerCamel case

Must be in plural form

This section describes a set of standard message field definitions that should be used when similar concepts are needed. This will ensure the same concept has the same name and semantics across different APIs.

If the API accepts client-assigned resource names, the server may allow the client to specify a non-existent resource name and create a new resource.

A batch get (such as a method that takes multiple resource ids and returns an object for each of those ids) should be implemented as a custom BatchGet method, rather than a List

Batch get of multiple resources.

If the Update method only supports full resource update, it must use HTTP verb PUT

Sometimes an API client only needs a specific subset of data in the response message.

To reduce network traffic, it is sometimes useful to allow the client to limit which parts of the resource the server should return in its responses, returning a view of the resource instead of the full resource representation.

it may be useful to allow a Get to retrieve that resource without knowing which parent collection contains it

Promote an employee (corpeng) If implemented as a standard update, the client would have to replicate the corporate policies governing the promotion process to ensure the promotion happens to the correct level, within the same career ladder etc.

The standard Update method should support partial resource update, and use HTTP verb PATCH

Move a resource from one parent to another.

The resource name is organized hierarchically using collection IDs and resource IDs, separated by forward slashes.

A resource has some state and zero or more sub-resources. Each sub-resource can be either a simple resource or a collection resource.

The key characteristic of a resource-oriented API is that it emphasizes resources (data model) over the methods performed on the resources (functionality)