Google API Design Guide

Google

API Design

Global design

General considerations on API design

  • Resource Oriented Design
    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.
  • What is a REST API?
  • Design flow
    The Design Guide suggests taking the following steps when designing resource- oriented APIs
  • Design Patterns

API Lifecycle

Updates and Versioning

How to handle API updates and versioning

Asynchronicity

Asynchronicity

How to handle long operations

Collection Resources

Retrieve a collection

How to get a collection or resources

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

Sorting a collection

How to sort a collection of resources

Collection

What is a collection (set) of resources

  • Resources
    A collection contains a list of resources of the same type. For example, a user has a collection of contacts.
  • Methods
    The key characteristic of a resource-oriented API is that it emphasizes resources (data model) over the methods performed on the resources (functionality)
  • Resources examples
  • Collection ID

Pagination

How to retrieve a range of resources in a collection

Filtering

How to select some resources in a collection

Data

Data format

which data format use

Date and Time

How to deal with date and time data

HTTP Methods

PUT

The PUT method requests that the enclosed entity be stored under the supplied URI. If the URI refers to an already existing resource, it is modified; if the URI does not point to an existing resource, then the server can create the resource with that URI.

GET

The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect.

POST

The POST method requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI. The data POSTed might be, for example, an annotation for existing resources; a message for a bulletin board, newsgroup, mailing list, or comment thread; a block of data that is the result of submitting a web form to a data-handling process; or an item to add to a database.

PATCH

The PATCH method applies partial modifications to a resource.

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

DELETE

The DELETE method deletes the specified resource.

HTTP methods

General information about HTTP methods usage

HTTP Protocol

Content negociation and media types

How to describe your API data format and/or propose different formats (like json, yaml, xml atom, …)

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

Caching

How to use and provide relevant caching informations

Miscellaneous

Guiding inputs

How to help consumers or end user to input relevant data

  • Request Validation
    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.
  • Request Duplication
    some API methods cannot easily be idempotent, such as creating a resource, and there is a need to avoid unnecessary duplication
  • Grammar Syntax
  • Output Fields
    This means that the server must ignore the presence of output only fields and any indication of it.

Documentation

How to produce and/or propose API documentation

  • Grammar Syntax
    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
  • Output Fields
    For fields that are output only, the field attribute shall be documented.
  • Documentation
    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.
  • Checklist for all descriptions
    In most cases, there's more to say than just restating the obvious

Developer experience

How to take care of developer experience (DX)

  • Grammar Syntax
    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

Undo

How to undo things

  • Delete
    If the Delete method only marks the resource as being deleted, it should return the updated resource.
  • Undelete
    Restore a resource that was previously deleted. The recommended retention period is 30-day.

Naming

Naming

How to name things

Language

Which language(s) use when designing an API

Case

Which case (lowercase, camelCase, …) to use and when

Resources

Create resource

How to create resources

Delete resource

How to delete resources

Create resource with a specific ID

How to create resource with a provided id

  • Update
    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.

Batch Bulk

How to handle batch/bulk processing/creation/update/… (e.g. handle multiple resources at conce)

  • Batch Get
    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
  • Common Custom Methods
    Batch get of multiple resources.

Replace resource

How to replace (or update fully) a resource

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

Retrieve resource partially

How to retrieve partially a resource

  • Partial Response
    Sometimes an API client only needs a specific subset of data in the response message.
  • Resource View
    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.

Retrieve resource

How to retrieve a resource

Resource's state

How to change a resource’s state/status (like processed/sent/paid/…)

  • Use Cases
    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.

Update resource partially

How to udate partially a resource

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

Update resource

How to update a resource

URL format

How to design URLs

Resource

General informations about resources

  • Resources
    A resource has some state and zero or more sub-resources. Each sub-resource can be either a simple resource or a collection resource.
  • Methods
    The key characteristic of a resource-oriented API is that it emphasizes resources (data model) over the methods performed on the resources (functionality)
  • Resources examples
  • Resource Labels

Action resource

How to use action resource (e.g. resources like /cancel or /approve)

Resource ID

What is a resource ID and/or how it’s built