Download the PHP package csenayeem025/google-workspace-sdk without Composer

Google Workspace SDK

Overview

The Google Workspace SDK is an open source Composer package created by GitLab IT Engineering for use in the GitLab Access Manager Laravel application for connecting to Google API endpoints for provisioning and deprovisioning of users, groups, group membership, and other related functionality.

Disclaimer: This is not an official package maintained by the Google or GitLab product and development teams. This is an internal tool that we use in the GitLab IT department that we have open sourced as part of our company values.

Please use at your own risk and create issues for any bugs that you encounter.

Dependencies

Note: This package will require the glamstack/google-auth-sdk package in order to operate. This is already configured as a required package in the composer.json file and should be automatically loaded when installing this package.

All configurations for this package by default will be configured under the glamstack-google-workspace.php file that will be loaded when this package is installed. For further guidance please see the Installation docs

Maintainers

How It Works

The package utilizes the glamstack/google-auth-sdk package for creating the Google JWT Web Token to authenticate with Google Workspace API's.

For more information on glamstack/google-auth-sdk please see the Google Auth SDK README.md.

This package is not intended to provide functions for every endpoint for Google Workspace API's. The endpoints will be constructed on an as needed basis. If you wish to add any additional endpoints please see CONTRIBUTING.

If the endpoint that you need is not created yet we have provided the REST class that can perform GET, POST, PUT, and DELETE requests to any endpoint that you find in the Google Workspace API's documentation and the class will handle the API response, error handling, and pagination for you.

:warning: PATCH request are not currently working but will be implemented in the future.

This package builds upon the simplicity of the Laravel HTTP Client that is powered by the Guzzle HTTP client to provide "last lines of code parsing" for Google Workspace API's responses to improve the developer experience.

Package Initialization

This package is initialized via a configuration see How To Initialize With Configuration File for instructions on both initialization methods.

Installation

Requirements

Add Composer Package

This package uses Calendar Versioning.

We recommend always using a specific version in your composer.json file and reviewing the changelog to see the breaking changes in each release before assuming that the latest release is the right choice for your project.

If you are contributing to this package, see CONTRIBUTING for instructions on configuring a local composer package with symlinks.

Publish the configuration file

Version upgrades

If you have upgraded to a newer version of the package, you should back up your existing configuration file to avoid your custom configuration being overridden.

Calendar Versioning

The GitLab IT Engineering team uses a modified version of Calendar Versioning (CalVer) instead of Semantic Versioning (SemVer). CalVer has a YY (Ex. 2021 => 21) but having a version 21.xx feels unintuitive to us. Since our team started this in 2021, we decided to use the last integer of the year only (2021 => 1.x, 2022 => 2.x, etc).

The version number represents the release date in vY.M.D format.

Why We Don't Use Semantic Versioning

1. We are continuously shipping to main/master/production and make breaking changes in most releases, so having semantic backwards-compatible version numbers is unintuitive for us.
2. We don't like to debate what to call our release/milestone and whether it's a major, minor, or patch release. We simply write code, write a changelog, and ship it on the day that it's done. The changelog publication date becomes the tagged version number (Ex. 2022-02-01 is v2.2.1). We may refer to a bigger version number for larger releases (Ex. v2.2), however this is only for monthly milestone planning and canonical purposes only. All code tags include the day of release (Ex. v2.2.1).
3. This allows us to automate using GitLab CI/CD to automate the version tagging process based on the date the pipeline job runs.
4. We update each of our project composer.json files that use this package to specific or new version numbers during scheduled change windows without worrying about differences and/or breaking changes with "staying up to date with the latest version". We don't maintain any forks or divergent branches.
5. Our packages use underlying packages in your existing Laravel application, so keeping your Laravel application version up-to-date addresses most security concerns.

Initializing the SDK

Initialization of the API Client can be done either by passing in a (string) connection_config

Google API Authentication

The package utilizes the glamstack/google-auth-sdk package for creating the Google JWT Web Token to authenticate with Google Cloud API endpoints.

For more information on glamstack/google-auth-sdk please see the Google Auth SDK README.md.

Connection Keys

We use the concept of connection keys that refer to a configuration array in config/glamstack-google-workspace.php that allows you to pre-configure one or more API connections.

Each connection key is associated with a GCP service account JSON key. This can be used to configure different auth scope connections and permissions to your GCP organization or different GCP project(s) depending on the API calls that you're using. This allows for least privilege for specific API calls, and you can also configure multiple connections with the same GCP project and different API tokens that have different permission levels.

Example Connection Key Initialization

Example Connection Key Configuration

Dynamic Connection Config Array

If you don't want to pre-configure your connection and prefer to dynamically use connection variables that are stored in your database, you have the ability to pass in the required configurations via an array (See Example Connection Config Array Initialization) using the connection_config array in the second argument of the ApiClient construct method.

Required Parameters

Using a JSON Key File on your filesystem

Using a JSON Key String in your database

Security Warning: You should never commit your service account key (JSON contents) into your source code as a variable to avoid compromising your credentials for your GCP organization or projects.

It is recommended to convert the JSON key to a base 64 encoded string before encryption since this is the format used by the GCP Service Account API for the privateKeyData field.

The example below shows the value of the JSON key that is stored in your database.

Custom Logging Configuration

By default, we use the single channel for all logs that is configured in your application's config/logging.php file. This sends all Google Workspace log messages to the storage/logs/laravel.log file.

If you would like to see Google Workspace logs in a separate log file that is easier to triage without unrelated log messages, you can create a custom log channel. For example, we recommend using the value of glamstack-google-workspace, however you can choose any name you would like.

Add the custom log channel to config/logging.php.

Update the channels.stack.channels array to include the array key (ex. glamstack-google-workspace) of your custom channel. Be sure to add glamstack-google-workspace to the existing array values and not replace the existing values.

REST API Request

You can make an API request to any of the resource endpoints in the Google Workspace Admin SDK Directory Documentation.

Inline Usage

GET Request

The endpoints when uiltizing the REST class will require the full URL of the endpoint.

For examples, the List Google Workspace Users API Documentation shows the endpoint

With the SDK, you use the get() method with the endpoint for Google Workspace Users.

You can also use variables or database models to get data for constructing your endpoints.

Here are some more examples of using endpoints.

GET Requests with Query String Parameters

The second argument of a get() method is an optional array of parameters that is parsed by the SDK and the Laravel HTTP Client and rendered as a query string with the ? and & added automatically.

POST Requests

The post() method works almost identically to a get() request with an array of parameters, however the parameters are passed as form data using the application/json content type rather than in the URL as a query string. This is industry standard and not specific to the SDK.

You can learn more about request data in the Laravel HTTP Client documentation.

PUT Requests

The put() method is used for updating an existing record (similar to PATCH requests). You need to ensure that the ID of the record that you want to update is provided in the first argument (URI).

In most applications, this will be a variable that you get from your database or another location and won't be hard-coded.

DELETE Requests

The delete() method is used for methods that will destroy the resource based on the ID that you provide.

Keep in mind that delete() methods will return different status codes depending on the vendor (ex. 200, 201, 202, 204, etc). Google Workspace API's will return a 204 status code for successfully deleted resources.

Class Methods

The examples above show basic inline usage that is suitable for most use cases. If you prefer to use classes and constructors, the example below will provide a helpful example.

API Responses

This SDK uses the GLAM Stack standards for API response formatting.

API Response Headers

API Response Specific Header

API Response JSON

API Response Object

API Response Status

See the Laravel HTTP Client documentation to learn more about the different status booleans.

API Response Status Code

Error Handling

The HTTP status code for the API response is included in each log entry in the message and in the JSON status_code. Any internal SDK errors also included an equivalent status code depending on the type of error. The message includes the SDK friendly message. If an exception is thrown, the reference

If a 5xx error is returned from the API, the GoogleWorkspaceApiClient handleException method will return a response.

See the Log Outputs below for how the SDK handles errors and logging.

Log Outputs

The output of error messages is shown in the README to allow search engines to index these messages for developer debugging support. Any 5xx error messages will be returned as as Symfony\Component\HttpKernel\Exception\HttpException or configuration errors, including any errors in the ApiClient::setApiConnectionVariables() method.

Issue Tracking and Bug Reports

Please visit our issue tracker and create an issue or comment on an existing issue.

Contributing

Please see CONTRIBUTING.md to learn more about how to contribute.-