googleapis / googleapis.github.io

The GitHub pages site for the googleapis organization.

Google APIs

The googleapis organization hosts tools, technical articles, and issues related to Google API design and practice. It also hosts client libraries for using many Google APIs from a variety of supported languages.

Here we use Google APIs to refer to networked APIs provided by Google services. Google APIs are developed as RPC API services defined using Protocol Buffers. These RPC APIs are published directly as gRPC services and are made available as REST APIs using gRPC-HTTP/JSON Transcoding. Most Google APIs are hosted on the googleapis.com domain, and Google API specifications are published in github.com/googleapis/googleapis. External developers can use the published proto files to generate documentation and client libraries or to guide their own API definitions.

API Design Guide

Google APIs use a common API Design Guide that encourages a simple and consistent API design philosophy. It also provides solutions to common design issues, such as proper default values for enums and patterns for long-running operations.

How to Call Google APIs

The easiest way to call a Google API is with a Google Cloud Client Library:

• Go
• Java
• Node.js
• Python
• Ruby
• PHP
• C#

All client libraries are fully open-source and are released under the Apache License, Version 2.0.

For developers working in languages or environments that we don't support, we provide instructions here for calling Google APIs in both REST and RPC forms:

• How to Call Google APIs, REST edition

• How to Call Google APIs, RPC edition

API Client Tools

Google's API client libraries are produced with open source tools and automation.

Generated API Clients (GAPICs)

Google's newest and most powerful APIs are built with gRPC, an open-source RPC framework that grew from technologies developed at Google. Many of the client libraries that we publish for these APIs are automatically generated from API descriptions written in the Protocol Buffers language. All of our generators and related tools are open source and hosted in the googleapis organization. To learn more about them, see gapic-generators.

The googleapis organization also hosts repositories that contain common code used by Google's generated and handwritten client libraries. Details vary by language, but most provide support for generally-needed features like paging and retry. Currently there is one such library for each of the main languages that we support: gax-dotnet, gax-go, gax-java, gax-nodejs, gax-php, gax-python, and gax-ruby. Note that we consider these to be internal implementation details of our clients and reserve the right to make changes, so if you choose to use them, be sure to refer to tagged versions.

The API Discovery Format

Before gRPC, Google APIs were published primarily as REST APIs and described with the Google API Discovery Service. Now via gRPC-HTTP/JSON Transcoding, many of Google's gRPC APIs are also available as HTTP/JSON APIs and described by the API Discovery Service. These HTTP/JSON APIs have been supported by a previous generation of client libraries and code generators based on the API Discovery Service. Google API support teams published support for several programming languages (Java, Python, PHP, .NET, Javascript, Ruby, Go, Node.js, and Objective-C). We also currently have experimental support for Swift. Support for other languages has been developed by external developers (Rust) and other groups within Google (Dart).

Currently, we are not aware of any other API provider using the API Discovery Format. In contrast, a large community of API producers and consumers has grown around the OpenAPI Specification (formerly known as Swagger), with many community tools emerging for working with OpenAPI descriptions of REST APIs.

OpenAPI

We recommend using OpenAPI and OpenAPI-based tools for working with Google's REST APIs. Several tools for converting Google Discovery Format to OpenAPI have been published:

• google-discovery-to-swagger, an MIT-licensed open source script for converting Google Discovery format into Swagger 2.0.
• API Spec Converter, an online converter from LucyBot.
• The API Transformer from APIMatic.

Google's OpenAPI tools include gnostic, a front-end for OpenAPI tools that reads OpenAPI descriptions, puts them in an efficient binary representation, and allows efficient plugins and standalone tools to be easily written in any programming language with Protocol Buffer support.

Issues

If you have feedback or questions regarding API design or methodology, please file an issue in the googleapis.github.io issues area. For specific tool questions, please file an issue on the corresponding repository. We look forward to hearing from you!