platform-client-sdk-go

module
Version: v33.0.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 19, 2021 License: MIT

README


title: Platform API Client SDK - Go

A Go package to interface with the Genesys Cloud Platform API. View the documentation on the pkg.go.dev. Browse the source code on Github.

Latest version: 33.0.0 GitHub release Release Notes Badge

Golang Version Dependency

:::danger Some macOS users encounter the error "argument list too long" when building or installing this package if their golang version is less than 1.15. Visit Go Downloads and install go1.15 or newer if this error is thrown. :::

Get SDK Package

Retrieve the package from https://github.com/MyPureCloud/platform-client-sdk-go using go get:

go get github.com/mypurecloud/platform-client-sdk-go/platformclientv2

Using the SDK

Importing the package

import (
	"github.com/MyPureCloud/platform-client-sdk-go/platformclientv2"
)

Configuring the SDK

The SDK can be configured by setting properties on a Configuration instance. Applications that are using a single access token (most use cases) can use the default configuration.

The default configuration will be used when creating new API instances without supplying the config.

// Get default config to set config options
config := platformclientv2.GetDefaultConfiguration()

// Create API instance using default config
usersAPI := platformclientv2.NewUsersApi()

Applications that will be making requests using multiple access tokens can create multiple configuration instances and authorize them individually. This is a common pattern when using the SDK in a backend web server where multiple Genesys Cloud users will authenticate using an auth code grant.

When creating configuration instances, they must be used when creating new API instances.

// Create new config
config := platformclientv2.NewConfiguration()

// Create API instance using config
usersAPI := platformclientv2.NewUsersApiWithConfig(config)
Setting the environment

To connect to regional Genesys Cloud instances, provide the Platform API's base path:

config.BasePath = "https://api.mypurecloud.jp"
Setting the access token

If using a grant other than client credentials and code authorization, the access token can be set manually:

config.AccessToken = "anaccesstokenobtainedmanuallyfromanoauthgrant"
Enable debug logging

Enabling debug logging will trace out information about all requests and responses:

config.SetDebug(false)

Authorization

Client Credentials

The SDK provides a helper to authorize using client credentials. Use the AuthorizeClientCredentials function on the client to make a request to Genesys Cloud to exchange the client id and secret for an access token. If no error was returned, the configuration instance is now authorized and can begin making API requests.

err := config.AuthorizeClientCredentials(os.Getenv("GENESYS_CLOUD_CLIENT_ID"), os.Getenv("GENESYS_CLOUD_CLIENT_SECRET"))
if err != nil {
    panic(err)
}
Authorization Code Grant
  • The app is authenticating as a human, the Authorization Code Grant
  • The app is served via a web server
  • There is server-side code that will be making API requests

Use the AuthorizeCodeGrant function on the client to make a request to Genesys Cloud to exchange the client id, client secret and authorization code for an access token. If no error was returned, the configuration instance is now authorized and can begin making API requests.

authData, err := config.AuthorizeCodeGrant(clientId, clientSecret, authCode, redirectUri)
if err != nil {
    panic(err)
}

By default the SDK will transparently request a new access token when it expires. If multiple threads are running 1 thread will request a new token, other threads will wait a maximum of 10 seconds for the token refresh to complete, this time can be overriden with the RefreshTokenWaitTime field of the Configuration struct.
If you wish to apply the refresh logic yourself, set ShouldRefreshAccessToken to false and store the refresh token. The ExpiresIn member of the authData struct can be used to preemptively request a new token. Use RefreshAuthorizationCodeGrant to request a new token when necessary

config.ShouldRefreshAccessToken = false
// When token expires
authData, err := config.RefreshAuthorizationCodeGrant(clientId, clientSecret, authData.RefreshToken)
if err != nil {
    panic(err)
}

Making Requests

Once the SDK is authorized, API requests can be made. Each function on the API instance returns three values, or just the latter two if the resource does not return any value (e.g. a DELETE operation):

  • A struct representing the API response. This will be nil if any error occurred.
  • An APIResponse instance providing extended information about the response. This is useful for debugging, custom logging, and advanced error handling. This may be nil under certain error circumstances. This will have a value when the API returns an error.
  • An error, if any error occurred at any point during processing.
userID := "asdf1234-5678-90ab-cde1-123456789012"
usersAPI := platformclientv2.NewUsersApi()

user, response, err := usersAPI.GetUser(userID, make([]string, 0), "")
fmt.Printf("Response:\n  Success: %v\n  Status code: %v\n  Correlation ID: %v\n", response.IsSuccess, response.StatusCode, response.CorrelationID)
if err != nil {
    fmt.Printf("Error calling GetUser: %v\n", err)
} else {
    fmt.Printf("Hello, %v\n", *user.Name)
}

Versioning

The SDK's version is incremented according to the Semantic Versioning Specification. The decision to increment version numbers is determined by diffing the Platform API's swagger for automated builds, and optionally forcing a version bump when a build is triggered manually (e.g. releasing a bugfix).

Support

This package is intended to be forwards compatible with v2 of Genesys Cloud's Platform API. While the general policy for the API is not to introduce breaking changes, there are certain additions and changes to the API that cause breaking changes for the SDK, often due to the way the API is expressed in its swagger definition. Because of this, the SDK can have a major version bump while the API remains at major version 2. While the SDK is intended to be forward compatible, patches will only be released to the latest version. For these reasons, it is strongly recommended that all applications using this SDK are kept up to date and use the latest version of the SDK.

For any issues, questions, or suggestions for the SDK, visit the Genesys Cloud Developer Forum.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL