Google APIs Explorer

Overview

The Google APIs Explorer is a tool for exploring Google APIs interactively. The Google APIs explorer allows you to try API methods without writing code.

Accessing APIs

Supported APIs

APIs Explorer supports most Google APIs. The supported APIs are displayed on the index page of the APIs Explorer.

Sample request

To use the books API to search for the book named "Hunger Games", click the following link and then click Execute: search for the book named "Hunger Games". The results appear under application/json.

Authenticating to the APIs

By default, the APIs Explorer uses its own API key when it makes a request. When you use the APIs Explorer to make a request, it displays the request syntax, which includes a placeholder labeled {YOUR_API_KEY}. If you want to make the same request in your application, you need to replace this placeholder with your own API key.

Authenticating to the APIs using custom credentials

Using the APIs Explorer's default API key and client id is simple and avoids common issues. You can choose to override the default API key and/or client ID with your own.

To create custom credentials and use them in APIs Explorer, follow these steps:

  1. Open the Google Developers console for your Google developers project.
  2. Click Create credentials and then click API key. Save the API key.
  3. Click Create credentials and then click Create OAuth client ID. Follow the prompts and then save the OAuth client ID.
  4. In the APIs Explorer, enter the credentials you created in the Set API key / OAuth 2.0 Client ID field.

For privacy reasons, the data entered into the APIs explorer is only stored in local memory, so you will need to re-enter the custom values every time you re-visit the Explorer site, or the defaults will be used.

Before you make a request using custom credentials, make sure that the following prerequisites are met:

  • The custom API key and client ID are from the same Google developers project
  • The APIs Explorer's domain (developers.google.com) is allowed as a referrer for your API key
  • The API Explorer's domain is allowed as a JavaScript origin for your client ID
  • The API(s) you're calling are enabled for the project that the credentials are associated with

Supported data formats

The APIs Explorer supports JSON for responses and request payloads. Although some Google APIs support other data formats, such as XML-based formats like AtomPub and Portable contacts, when using these APIs in the API Explorer, you must use JSON.

Authorized access

Authorizing a request using OAuth 2.0

Certain API requests access your private data, for example, a request to list the buckets in your project. These requests require that you authorize the APIs Explorer to access your data. The API Explorer then sends authentication credentials that verify that it is authorized to access data on your behalf. This is known as authenticated access. The first time you try to make an authenticated request, the Explorer presents a dialog asking you to grant it access to a limited set of your private data.

Many API methods only access public data. These methods don't require you to send authentication credentials, and requests can be made using unauthenticated access. Some methods support public and private access. These methods can behave differently depending on whether authentication credentials are provided. The Explorer allows you to switch between authenticated and unauthenticated requests so that you can see how the API behaves in these scenarios.

The scope of authorized access

When you make an authenticated request to an API, the APIs Explorer asks you to grant it permission to access data on your behalf. The specific data that the Explorer can access is limited by the “scope,” which is particular to an API. In other words, the scope limits the power of the access you grant. For example, the Calendar API allows you to grant access to the APIs Explorer using a read-only scope or a regular scope. Before making the first authenticated call, the Explorer asks you to choose the scope to use when granting it access to your data.

Different methods might require different scopes. For example, a method in an API might require at least a read-only scope, while other methods might require a read-write scope. If you are making an authenticated call and selecting a scope, the APIs Explorer will tell you which scopes are required for calling a method in the selected API. Making a request with OAuth credentials obtained using the wrong scope might result in a failed request. If this occurs, you can reset the switch to Authorize your API calls and use a different scope.

Troubleshooting authorizing access

If you click Authorize in the select scopes dialog and nothing happens, you might need to change your browser's popup settings. The APIs Explorer uses a popup to ask you to grant access to your private data. If your browser blocks popups, this popup won't appear and you won't be able to grant access. Try changing your browser's popup settings. For example, Chrome shows you if a popup was blocked on the address bar.

Revoking authorized access

When you turn off Authorize requests using OAuth 2.0, the APIs Explorer stops sending authentication credentials. The Explorer remains authorized to make autenticated requests on your behalf for as long as the credentials you obtained are not expired. This is why you can turn on Authorize Requests using OAuth 2.0 without being asked to grant access again.

To revoke the permissions that you have given the Explorer to access data on your behalf, go to the Google Accounts page for managing authorization for applications. You can't revoke access directly from the Explorer.

Using Explorer with a local HTTP API

If you use Google Cloud Endpoints and you are running your Endpoint in a development server, your browser might give a warning about mixed content. Explorer is loaded over HTTPS, but when your API runs locally, it is hosted on HTTP.

To resolve this, using Chrome, you must start a Chrome session with special flags as follows:

[path-to-Chrome] --user-data-dir=test --unsafely-treat-insecure-origin-as-secure=http://localhost:port

The following sample demonstrates this command:

 /usr/bin/google-chrome-stable --user-data-dir=test --unsafely-treat-insecure-origin-as-secure=http://localhost:8080

You should only do this for local testing purposes, in which case you can ignore the warning banner displayed in the browser.