Tuesday, March 10, 2015
Tips on using the APIs Discovery Service
Our newest set of APIs - Tasks, Calendar v3, Google+ to name a few - are supported by the Google APIs Discovery Service. The Google APIs Discovery service offers an interface that allows developers to programmatically get API metadata such as:
- A directory of supported APIs.
- A list of API resource schemas based on JSON Schema.
- A list of API methods and parameters for each method and their inline documentation.
- A list of available OAuth 2.0 scopes.
The APIs Discovery Service is especially useful when building developer tools, as you can use it to automatically generate certain features. For instance we are using the APIs Discovery Service in our client libraries and in our APIs Explorer but also to generate some of our online API reference.
Because the APIs Discovery Service is itself an API, you can use features such as partial response which is a way to get only the information you need. Let’s look at some of the useful information that is available using the APIs Discovery Service and the partial response feature.
List the supported APIs
You can get the list of all the APIs that are supported by the discovery service by sending a GET request to the following endpoint:
https://www.googleapis.com/discovery/v1/apis?fields=items(title,discoveryLink)
Which will return a JSON feed that looks like this:
{
"items": [
…
{
"title": "Google+ API",
"discoveryLink": "./apis/plus/v1/rest"
},
{
"title": "Tasks API",
"discoveryLink": "./apis/tasks/v1/rest"
},
{
"title": "Calendar API",
"discoveryLink": "./apis/calendar/v3/rest"
},
…
]
}
Using the discoveryLink attribute in the resources part of the feed above you can access the discovery document of each API. This is where a lot of useful information about the API can be accessed.
Get the OAuth 2.0 scopes of an API
Using the API-specific endpoint you can easily get the OAuth 2.0 scopes available for that API. For example, here is how to get the scopes of the Google Tasks API:
https://www.googleapis.com/discovery/v1/apis/tasks/v1/rest?fields=auth(oauth2(scopes))
This method returns the JSON output shown below, which indicates that https://www.googleapis.com/auth/tasks and https://www.googleapis.com/auth/tasks.readonly are the two scopes associated with the Tasks API.
{
"auth": {
"oauth2": {
"scopes": {
"https://www.googleapis.com/auth/tasks": {
"description": "Manage your tasks"
},
"https://www.googleapis.com/auth/tasks.readonly": {
"description": "View your tasks"
}
}
}
}
}
Using requests of this type you could detect which APIs do not support OAuth 2.0. For example, the Translate API does not support OAuth 2.0, as it does not provide access to OAuth protected resources such as user data. Because of this, a GET request to the following endpoint:
https://www.googleapis.com/discovery/v1/apis/translate/v2/rest?fields=auth(oauth2(scopes))
Returns:
{}
Getting scopes required for an API’s endpoints and methods
Using the API-specific endpoints again, you can get the lists of operations and API endpoints, along with the scopes required to perform those operations. Here is an example querying that information for the Google Tasks API:
https://www.googleapis.com/discovery/v1/apis/tasks/v1/rest?fields=resources/*/methods(*(path,scopes,httpMethod))
Which returns:
{
"resources": {
"tasklists": {
"methods": {
"get": {
"path": "users/@me/lists/{tasklist}",
"httpMethod": "GET",
"scopes": [
"https://www.googleapis.com/auth/tasks",
"https://www.googleapis.com/auth/tasks.readonly"
]
},
"insert": {
"path": "users/@me/lists",
"httpMethod": "POST",
"scopes": [
"https://www.googleapis.com/auth/tasks"
]
},
…
}
},
"tasks": {
…
}
}
}
This tells you that to perform a POST request to the users/@me/lists endpoint (to insert a new task) you need to have been authorized with the scope https://www.googleapis.com/auth/tasks and that to be able to do a GET request to the users/@me/lists/{tasklist} endpoint you need to have been authorized with either of the two Google Tasks scopes.
You could use this to do some automatic discovery of the scopes you need to authorize to perform all the operations that your applications does.
You could also use this information to detect which operations and which endpoints you can access given a specific authorization token ( OAuth 2.0, OAuth 1.0 or Authsub token). First, use either the Authsub Token Info service or the OAuth 2.0 Token Info Service to determine which scopes your token has access to (see below); and then deduct from the feed above which endpoints and operations requires access to these scopes.
[Access Token] -----(Token Info)----> [Scopes] -----(APIs Discovery)----> [Operations/API Endpoints]
Example of using the OAuth 2.0 Token Info service:
Request:
GET /oauth2/v1/tokeninfo?access_token=HTTP/1.1
Host: www.googleapis.com
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
…
{
"issued_to": "1234567890.apps.googleusercontent.com",
"audience": "1234567890.apps.googleusercontent.com",
"scope": "https://www.google.com/m8/feeds/
https://www.google.com/calendar/feeds/",
"expires_in": 1038
}
There is a lot more you can do with the APIs Discovery Service so I invite you to have a deeper look at the documentation to find out more.
 | Nicolas Garnier profile | twitter | events Nicolas joined Google’s Developer Relations in 2008. Since then hes worked on commerce oriented products such as Google Checkout and Google Base. Currently, he is working on Google Apps with a focus on the Google Calendar API, the Google Contacts API, and the Tasks API. Before joining Google, Nicolas worked at Airbus and at the French Space Agency where he built web applications for scientific researchers. |
