Skip to content

Latest commit

 

History

History
136 lines (118 loc) · 4.45 KB

HowToREST.md

File metadata and controls

136 lines (118 loc) · 4.45 KB
Raw

How to Call Google APIs: REST Edition

For many developers, the easiest way to call a Google API is with one of our client libraries. But occasionally someone may prefer to make API calls directly - perhaps from a language or environment that we don’t support or using a different networking library or tool. Here we’ll show you how to do it.

This page focuses on calling Google APIs using JSON REST interfaces. Most of these APIs are also available as Protocol Buffer-based RPC services. For more on that, see How to Call Google APIs, RPC Edition.

What you’ll need

An API definition

Most Google APIs are available as JSON REST services. These APIs are formally described by the Google API Discovery Service in a JSON representation known as the Discovery Document format.

For an example, see the Cloud Natural Language API, which is defined by this Discovery Document. Human-readable documentation is in the Google Cloud Natural Language API reference. We’ll call the AnalyzeEntities service, which takes a block of text as input and returns a list of names and nouns that it finds in the text along with some interesting properties of each entity.

JSON

Google REST APIs use JSON for most message responses and POST bodies. Quoting www.json.org:

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999. JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.

Making REST API Requests

Google REST APIs are designed to be called by any standards-compliant HTTP client, including the curl command-line tool and library.

Authentication

To use Google APIs, a client needs to authenticate with an API key or an OAuth token. For more information, see the Google Cloud Authentication Overview.

API keys can be obtained from the Google Cloud Console > Credentials page. OAuth tokens can be obtained by OAuth 2 clients and libraries. For a sample command-line client, see the oauth2l on GitHub.

An example

Here is a simple example that uses curl to call the AnalyzeEntities service:

$ curl "https://language.googleapis.com/v1/documents:analyzeEntities" \
  -X POST \
  -H "X-Goog-Api-Key: $GOOGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document":{"content":"The rain in Spain stays mainly in the plain.", "type":"PLAIN_TEXT"}}' \
  -i
HTTP/2 200
content-type: application/json; charset=UTF-8
[other headers]

{
  "entities": [
    {
      "name": "rain",
      "type": "OTHER",
      "metadata": {},
      "salience": 0.67902344,
      "mentions": [
        {
          "text": {
            "content": "rain",
            "beginOffset": 4
          },
          "type": "COMMON"
        }
      ]
    },
    {
      "name": "plain",
      "type": "OTHER",
      "metadata": {},
      "salience": 0.17103066,
      "mentions": [
        {
          "text": {
            "content": "plain",
            "beginOffset": 38
          },
          "type": "COMMON"
        }
      ]
    },
    {
      "name": "Spain",
      "type": "LOCATION",
      "metadata": {},
      "salience": 0.1499459,
      "mentions": [
        {
          "text": {
            "content": "Spain",
            "beginOffset": 12
          },
          "type": "PROPER"
        }
      ]
    }
  ],
  "language": "en"
}