IBM Cloud Docs
Go

Go

Given its rapidly increasing popularity as a server-side language with strong cross-platform portability, Go support is imperative to increase adoption of your IBM Cloud service.

Environment support

Your Go SDK should support Go releases go1.20 and up.

Publishing

All Go SDKs should be publicly available in an IBM GitHub organization.

Your SDK should follow the semantic versioning best practices.

Community support

Allow your users to find answers to their questions. Users should be able to report problems on GitHub by raising issues on your SDK repository. Having a public Slack channel is a great way to engage with users who have questions specific to their use cases.

Style guidelines

You should follow the conventions from Golang "Effective Go" style guide.

You should use the standard development tools for Go to check style and code coverage.

Streaming support

If your API takes file parameters, you should accept Go file streams (e.g. io.ReadCloser) as an input type.

Dependencies

You should use the standard dependencies provided by Go, like net/http, os, strings, and fmt to write your code.

Objects for arguments

The methods of your SDK that represent operations of your service should take a single argument - an instance of an "options" struct. Each operation should have its own options struct which contains fields that represent the operation parameters.

Standard features

Authentication

You are not required to use a particular library to provide the authentication for your service.

Your SDK must support all of the authentication methods supported by your service.

Configuration

Your SDK should allow various SDK configuration properties (e.g. service URL, authentication credentials) to be supplied through an external configuration mechanism (e.g. properties file or environment variables) in addition to a programmatic path. This will relieve SDK users from focusing on configuration-related functionality and will allow applications using your SDK to be flexible and avoid 'hard-coding' configuration information inside the application code.

If you build this capability into your SDK, you must document this mechanism clearly with examples.

Using go-sdk-core

IBM go-sdk-core provides configuration and authentication support. You can use the existing functionality provided by this dependency in your SDK.

Documentation

Your SDK is not useful if your audience cannot understand how to consume it in order to do the basic operations for your service. Your SDK needs to contain the following resources to help your users:

Samples

For your Go SDK, you will want some simple code samples and explanations of what each does. Linking out to the API reference documentation for more advanced use is strongly encouraged.

At minimum, the samples should be included in the README.md file. They should communicate how to install the library, and complete the basic operations provided by your API.