Getting Started

This document provides the background information you need to use the Google APIs Discovery Service.

  1. Introduction
  2. Before you start
  3. APIs Discovery Service background
    1. Concepts
    2. Data model
    3. Operations
  4. Calling style
    1. REST

Introduction

This document is intended for developers who want to write client libraries, IDE plugins, and other tools for interacting with Google APIs. The Google APIs Discovery Service supports tools like these by exposing machine readable metadata about various Google APIs through a simple API.

Before you start

If you are unfamiliar with Discovery concepts, you should read through this documentation, experiment with the API, and look at the samples before starting to code.

The APIs Discovery Service provides only public methods that do not require authentication. In addition, unlike the requests you make to many other Google APIs, the requests you make to the Discovery Service API should not include an API key. If you do provide a key, the requests will fail. This behavior helps ensure that you don't accidentally disclose your API key when distributing tools that are based on the Google APIs Discovery Service.

APIs Discovery Service background

Concepts

The Google APIs Discovery Service is built upon two basic concepts:

  • APIs Directory: A list of all APIs that are supported by the APIs Discovery Service. Each directory entry shows details about a supported API, including its name, a brief description of what it does, and a link to its documentation. Each supported API can have multiple Directory entries, one for each of its supported versions.
  • Discovery document: A machine-readable description of a particular API. The Discovery document describes the surface for a particular version of an API. The document provides details on how to access the various methods of each API via RESTful HTTP calls. A Discovery document includes descriptions of the data and methods associated with the API, as well as information about available OAuth scopes, and descriptions of schemas, methods, parameters and available parameter values.

Data model

A resource is an individual data entity with a unique identifier. The Google APIs Discovery Service operates on two types of resources, based on the above concepts.

  • APIs Directory resource: Represents the set of supported APIs.

    A Directory entry for a specific API version contains four types of information:

    • Identification and description information, including name, version, title, and description.
    • Documentation information, including icons and a documentation link.
    • Status information, including status labels, and an indication as to whether or not this is the preferred version of the API.
    • Discovery document link, the URI of the discovery document for this API (given as a path relative to https://www.googleapis.com/discovery/v1).
  • Discovery Document resource: Represents a machine-readable description of a particular API.

    In addition to the information provided in the APIs Directory, a Discovery document also includes:

    • Schemas, which is a list of API resource schemas that describe the data you have access to in each API; the Google APIs Discovery Service schemas are based on JSON Schema.
    • Methods, including a list of API methods and available parameters for each method.
    • OAuth scopes, which identifies the list of OAuth scopes available for this API.
    • Inline documentation, which provides brief descriptions of schemas, methods, parameters and available parameter values.

The single Directory Collection is the conceptual container of the single APIs Directory resource, and the Discovery Document resources for each supported API.

More details about the the APIs Directory resource and the Discovery Document resource are provided in the Using the API and Reference documents.

Operations

You can invoke two different methods on collections and resources in the Google APIs Discovery Service, as described in the following table.

Operation Description REST HTTP mappings
list Lists all supported APIs. GET on the Directory resource URI.
getRest Gets a Discovery Document resource for a particular API. GET on a Discovery Document resource URI.

Calling style

REST

The supported Google APIs Discovery Service operations map directly to the REST HTTP GET verb, as described in Operations.

The specific format for Google APIs Discovery Service URIs are:

https://www.googleapis.com/discovery/v1/apis?parameters
https://www.googleapis.com/discovery/v1/apis/api/version/rest?parameters

where api is the identifier for a Discovery Document resource, and version is the identifier of the particular version of the API, , and parameters are any parameters to apply to the query. See Query parameter summary in the reference documentation for details

Details on the full set of URIs used for each supported operation in the API is summarized in the Google APIs Discovery Service Reference document.

Here are a couple of examples of how this works in the Google APIs Discovery Service.

List all the Google APIs Discovery Service supported APIs:

GET https://www.googleapis.com/discovery/v1/apis

Try it now in APIs Explorer!

Get the Discovery document for the URL Shortener API, version 1:

GET https://www.googleapis.com/discovery/v1/apis/urlshortener/v1/rest

Try it now in APIs Explorer!
{"cc_re__cc_re__cc_by_3_0": ["s=\"apiexp\">\n <a class=\"button\" target=\"_blank\"\n   href=\"//developers.google.com/apis-explorer/#p/discovery/v1/discovery.apis.getRest?&amp;api=urlshortener&amp;version=v1\"><img\n   class=\"apiexp-img\" src=\"https://developers.google.com/shared/images/popout-204e80-18.png\"> Try it now in APIs\n   Explorer!</a>\n</p>\n<br/>\n\n\n  \n  </div>\n  \n\n  \n        \n  \n\n\n\n\n\n\n\n        \n<div class=\"devsite-content-footer nocontent\">\n  \n  \n    <p>Except as otherwise noted, the content of this page is licensed under the <a href=\"http://creativecommons.org/licenses/by/3.0/\">Creative Commons Attribution 3.0 License</a>, and code samples are licensed under the <a href=\"http://www.apache.org/licenses/LICENSE-2.0\">Apache 2.0 License</a>. For details, see our <a href=\"https://developers.google.com/terms/site-policies\">Site Policies</a>. Java is a registered trademark of Oracle and/or its affiliates.</p>\n  \n\n  \n    \n    <p class=\"devsite-content-footer-date\" itemprop=\"datePublished\"\n       content=\"2015-05-26T03:53:59.340910\">\n      \n      Last updated May 26, 2015.\n    "]}