Quick Start

Last updated: Jan 25th, 2017

Get your API key

The first step to use the API is to get your API key. To do so, you must connect to the back-office as an administrator.

  1. In the menu, go to the Manage API access section
  2. Click on Request an API key
  3. Choose the scope of your key between Admin and User (more about scopes) and write a few words to explain what you'll use the API for. This is important as each request for an API key is validated by a human. Validate by clicking on Request an API key on the bottom right.

Your request will then be validated by our staff. This will usually take a few hours. You'll be notified by email once the key has been validated. You'll then be able to consult it by going to the Manage API access section again:

Your first API call

To test the API, you can open a terminal and use the curl HTTP client:


curl 'https://pt4dapi-dot-powertools-v2-prod.appspot.com/_ah/api/powertools/v2/workspaces?domain=yourdomain.com&actionUser=admin@yourdomain.com&api_key=<redacted>&maxResults=10'
        

Don't forget to replace yourdomain.com with your own G Suite domain, admin@yourdomain.com with the email address of your G Suite admin, and <redacted> with your API key. In this example, the /workspaces endpoint returns the list of workspaces for the domain, the maxResults=10 parameter limiting the number of results to 10.

Scopes

Each API key has a scope associated to it, either User or Admin. This scopes simply indicates the set of endpoints the key has access to. Keys with Admin scopes have access to all endpoints, while the User scope is restricted to only a subset of endpoints.

In the reference, the scope of an endpoint is shown next to its description when you unroll the list of endpoints for a given category. For example, the following screenshot shows that getting the list of workspaces has a scope User whereas creating a new workspace has a scope Admin:
Screenshot example for the scope section

User identification

When you hold an API key, you have power over your entire domain and can impersonate any user using a special field actionUser. This parameter identifies the user to impersonate to perform the action. It's a string which is either the user's Google ID or its email. If you want to just perform the action and you don't know what user to impersonate, you can pass the domain administrator.

Do not call the API from JavaScript clients

The ability to perform user impersonation means that anyone who has access to your API key can perform actions on behalf of any user. In particular, you shouldn't call the API directly from JavaScript clients. If you want to authenticate users for the API, the most common scheme is to authenticate users on your own back-end application and call the API with the ID of the authenticated user.

Using an API client

Doing API requests with curl can be cumbersome. Google provides libraries in various languages to easily perform API requests on their APIs. Since the Powertools API is powered by Google's own endpoints system, you can use such library to call the Powertools API. In this documentation, Python is used, but usage in other languages is similar. Go to the Google APIs Client Libraries page to check out for which languages Google provides an API client.

Install the Google API client in Python

The first step is to install the library, which you can do by running the following command:

Installing the Google Python API client:

$ pip install --upgrade google-api-python-client
            

Build the client object

The first thing you need to do is to build an object which will act as an abstraction of the Powertools API. API requests will then merely be a matter of method calls on the client object.

Building a client object in Python

from apiclient.discovery import build

DISCOVERY_URL = 'https://pt4dapi-dot-powertools-v2-prod.appspot.com/_ah/api/discovery/v1/apis/powertools/v2/rest'

client = build(
  'powertools',
  'v2',
  discoveryServiceUrl=DISCOVERY_URL
)
            

In the code snippet above, we start by importing the method build from the apiclient library. We then define the DISCOVERY_URL which is a constant that you can copy and paste. This URL allows the client to discover what endpoints are available on the API, and what kind of arguments / body they accept. We finally call the method build and give it all the necessary parameters so that it can build the client for the v2 of the Powertools API.

Call methods on the client object

By calling methods on the client object, you obtain resources. On resources, you can then execute operations. For example, the API contains the workspaces resource. On this resource, you can execute the list (among others) operation:

Getting the list of workspaces

result = client.workspaces().list(
  api_key=API_KEY,
  domain='yourdomain.com',
  actionUser='user@yourdomain.com',
  maxResults=10
).execute()

if 'workspaces' in result:
    print 'Found workspaces!'
    for ws in result['workspaces']:
        print 'Workspace name:', ws['name']
            

In the example above, we first retrieve the workspaces resource on the client before executing the list operation on it. The method accepts the various parameters recognized by the endpoint. Most importantly, the three variables that you must include in each and every call is your API key, your G Suite domain name and a actionUser to impersonate a user.

The variable returned by the method is a Python dictionary, obtained thanks to the JSON data returned by the API. This dictionary may or may not have a workspaces field which maps to a list of workspaces. It's a peculiarity of Google endpoints system that if a list is empty, then the corresponding field is altogether absent from the result.

It's also possible that you must get a resource from another resource. For example, if you want to add a user to a workspace, you need to call the insert method on the users resource of the workspaces resource:

Add a user as reader of a workspace

client.workspaces().users().insert(
  api_key=API_KEY,
  domain='mydomain.com',
  actionUser='user@yourdomain.com',
  workspaceId=WORKSPACE_ID,
  role='reader',
  userId='john.smith@mydomain.com'
).execute()
            

In the example above, we inserted user john.smith@mydomain.com as a reader of the workspace whose ID is a constant WORKSPACE_ID for the sake of this example.

Parameters given as arguments of the operation method corresponds to the path parameters or the query string parameters of the HTTP method. Additionally, some endpoints accepts a body. To pass a body to an endpoint, pass to the body argument of the operation method a dictionary containing the body's content:

Create a new workspace

client.workspaces().insert(
  api_key=API_KEY,
  domain='mydomain.com',
  actionUser='admin@mydomain.com',
  ownerId='admin@mydomain.com',
  managerId='admin@mydomain.com',
  body={
    'name': 'MyNewWorkspace',
    'pushToRoot': True,
    'restrictedSharing': True
  }
).execute()
            

In this last example, we added a new workspace. The underlying HTTP method is a POST method, so the endpoint accepts a request's body whose content describe the workspace to create. To do so, we pass a dictionary to the body parameter.

What's next

Head over to the tutorial to see how to use essential endpoints of the API, or go to the reference for a comprehensive documentation of all endpoints.