UW-Madison G Suite - Google Groups API

This document describes the process for obtaining access to and using the Google Groups API to create and manage Google Groups in the UW-Madison G Suite tenant programmatically.

Description

The Google Groups API provided by the UW-Madison G Suite Team offers campus customers a delegated means of interacting with the Google Groups API. The permissions granted are scoped to only allow modification of Google Groups that have been created by the application or have obtained proper authorization from an owner of the group.


Getting Access

  1. Login to the Developer Portal.
  2. Create a new App. From the drop-down next under yournetid@wisc.edu, select Apps, then click +New App, or use an existing App if appropriate.
  3. Locate the APIs section and click Request next to the Google Groups API.
  4. Access requires approval from the G Suite Team. Email uw-gsuite-support@office365.wisc.edu with a description of your project how it will use the Google Groups API.
  5. Wait for approval or follow-up questions. The G Suite Team will email you when your request has been approved.
  6. Register your application using the POST "/register" end-point within the API. You can use "Try this API" from the the API documentation or do so programmatically. An example with curl is shown below under "Example query".
    • Note: The WSO2 API Store is deprecated. The POST /register route from the WSO2 API Store will no longer function and instead returns a 404 Not Found error.
  7. Your application should able to query the API immediately.

Google API Documentation

Google Groups API: https://developers.google.com/admin-sdk/directory/v1/reference/groups

Google Group Settings API: https://developers.google.com/admin-sdk/groups-settings/v1/reference/groups


Querying through Google Groups API Proxy

Your application will not be able to query the Google Groups APIs directly. Instead, the requests are proxied through API Proxy to handle proper authorization. All query paths should be modified to start with "https://api.wisc.edu/ggroups/...", and the remainder of the path follows the Google paradigm, such as "admin/directory/v1/groups" or "groups/v1/groups".

Example paths:

  • Create a group: POST https://api.wisc.edu/ggroups/admin/directory/v1/groups (with body content)
  • Get group details: GET https://api.wisc.edu/ggroups/admin/directory/v1/groups/mygroup%40g-groups.wisc.edu
  • Update group settings: PUT https://api.wisc.edu/ggroups/groups/v1/groups/mygroup%40g-groups.wisc.edu (with body content)

Paths and methods for those paths are shown in API documentation under the "Paths" section. Note that paths many paths include a {variable}, such as {groupEmail}, that needs to be replaced with the appropriate value(s). Except for the modified path above, all paths, parameters, and etc outlined in Google's documentation should function. If you find exceptions or problems, please report them to the G Suite team.

You must always include Authorization Bearer token obtained from the Developer Portal; do not attempt to include a Google API Authorization Bearer token. Your application is authorized to create any Google Group (unless it exists already, which returns 409), but the domain must be "g-groups.wisc.edu" or you will receive a "403 Forbidden" result. Your application is authorized to view or modify any group this application has created, but not any other groups.

Example Queries with curl:

Register an application
curl -X POST "https://api.wisc.edu/ggroups/register" -H "Authorization: Bearer Abcdefghijklmnopqrstuvwxyz"
Create a group
curl -X POST "https://api.wisc.edu/ggroups/admin/directory/v1/groups" -H "accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer Abcdefghijklmnopqrstuvwxyz" -d '{"email": "mygroup@g-groups.wisc.edu", "name": "mygroup", "description": "My group"}'

Grant Authorization for existing Google Group

In order for a registered application to view or modify an existing Google Group, the application ID must first be granted access. This can only be done by an existing owner of the group. To add authorization to an application that has been registered (above) for a Google Group that already exists, follow these steps as a user who has the owner role within the Google Group:

  1. Log into the Wisc Account Administration site and select the "Groups API" page in the "G Suite" menu.
  2. Enter the Google Group email address as the "Google Group ID"; e.g. "mygroup@g-groups.wisc.edu"
  3. Enter the Application ID that you want to grant authorization to. This is case-sensitive; e.g. "UNIVERSITYO5603/yournetid@wisc.edu@universityo5603/Hello World"
  4. Click Grant Authorization. Authorization is effective immediately upon success.

The application must be subscribed and registered to the Google Groups API for this to work. The owner of the application will see the authorization(s) granted to their application on the same page.


Notes and Reminders

  • API Proxy tokens expire must be refreshed.
  • There are throttling quotas applied by Google that you may run up against.
  • Adding aliases to groups is prevented at this time.
  • The email address of all groups must be in the "g-groups.wisc.edu" domain. Attempting to create or change the address of a group to another domain will fail.
  • If you change the email address of a group, your application will lose authorization to modify that group and will need to be reapplied.
  • Groups created with the Google Groups API have no owners or members. Unless owners are added, the only way to modify these groups is using the Google Groups API.
  • To leverage this API, you must be full-time faculty/staff, or use an application shared with you by someone who is.




Keywords:google groups api manage store ggroups ggroup   Doc ID:94234
Owner:Jacob F.Group:Google Apps
Created:2019-08-30 15:13 CSTUpdated:2021-11-10 10:46 CST
Sites:Google Apps
Feedback:  2   0