AWS Developer Tools Blog

AWS SDK for Go 2.0 Developer Preview

As of January 19th, 2021, the AWS SDK for Go, version 2 (v2) is generally available.

We’re pleased to announce the Developer Preview release of the AWS SDK for Go 2.0. Many aspects of the SDK have been refactored based on your feedback, with a strong focus on performance, consistency, discoverability, and ease of use. The Developer Preview is here for you to provide feedback, and influence the direction of the AWS SDK for Go 2.0 before its production-ready, general availability launch. Tell us what you like, and what you don’t like. Your feedback matters to us. Find details at the bottom of this post on how to give feedback and contribute.

You can safely use the AWS SDK for Go 2.0 in parallel with the 1.x SDK, with both SDKs coexisting in the same Go application. We won’t drop support for the 1.0 SDK any time soon. We know there are a lot of customers depending on the 1.x SDK, and we will continue to support them. As we get closer to general availability for 2.0, we’ll share a more detailed plan about how we’ll support the 1.x SDK.

Getting started

Let’s walk through setting up an application with the 2.0 SDK. We’ll build a simple Go application using the 2.0 SDK to make a service API request. For this walkthrough, you’ll need to use a minimum of Go 1.9.

  1. Create a new Go file for the example application. We’ll name ours main.go in a new directory, awssdkgov2-example, in our Go Workspace. 
    mkdir -p $(go env GOPATH)/src/awssdkgov2-example
cd $(go env GOPATH)/src/awssdkgov2-example

    All of the following steps assume you will execute them from the awssdkgov2-example directory.

  2. To get the AWS SDK for Go 2.0, you can go get the SDK manually or use a dependency management tool such as Dep. You can manually get the 2.0 SDK with go get github.com/aws/aws-sdk-go-v2.
  3. In your favorite editor create a main.go file, and add the following code. This code loads the SDK’s default configuration, and creates a new Amazon DynamoDB client. See the external package for more details on how to customize the way the SDK’s default configuration is loaded. 
    package main

import (
    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/aws/endpoints"
    "github.com/aws/aws-sdk-go-v2/aws/external"
    "github.com/aws/aws-sdk-go-v2/service/dynamodb"
)

func main() {
    // Using the SDK's default configuration, loading additional config
    // and credentials values from the environment variables, shared
    // credentials, and shared configuration files
    cfg, err := external.LoadDefaultAWSConfig()
    if err != nil {
        panic("unable to load SDK config, " + err.Error())
    }

    // Set the AWS Region that the service clients should use
    cfg.Region = endpoints.UsWest2RegionID

    // Using the Config value, create the DynamoDB client
    svc := dynamodb.New(cfg)
}
  4. Build the service API request, send it, and process the response. 
    // Build the request with its input parameters
req := svc.DescribeTableRequest(&dynamodb.DescribeTableInput{
    TableName: aws.String("myTable"),
})

// Send the request, and get the response or error back
resp, err := req.Send()
if err != nil {
    panic("failed to describe table, "+err.Error())
}

fmt.Println("Response", resp)

What has changed?

Our focus for the 2.0 SDK is to improve the SDK’s development experience and performance, make the SDK easy to extend, and add new features. The changes made in the Developer Preview target the major pain points of configuring the SDK and using AWS service API calls. Check out our 2.0 repo for details on pending changes that are in development and designs we’re discussing.

The following are some of the larger changes included in the AWS SDK for Go 2.0 Developer Preview.

SDK configuration

The 2.0 SDK simplifies how you configure the SDK’s service clients by using a single Config type. This simplifies the Session and Config type interaction from the 1.x SDK. In addition, we’ve moved the service-specific configuration flags to the individual service client types. This reduces confusion about where service clients will use configuration members.

We added the external package to provide the utilities for you to use external configuration sources to populate the SDK’s Config type. External sources include environmental variables, shared credentials file (~/.aws/credentials), and shared config file (~/.aws/config). By default, the 2.0 SDK will now automatically load configuration values from the shared config file. The external package also provides you with the tools to customize how the external sources are loaded and used to populate the Config type.

You can even customize external configuration sources to include your own custom sources, for example, JSON files or a custom file format.

Use LoadDefaultAWSConfig in the external package to create the default Config value, and load configuration values from the external configuration sources.

cfg, err := external.LoadDefaultAWSConfig()

To specify the shared configuration profile load used in code, use the WithSharedConfigProfile helper passed into LoadDefaultAWSConfig with the profile name to use.

cfg, err := external.LoadDefaultAWSConfig(
	external.WithSharedConfigProfile("gopher")
)

Once a Config value is returned by LoadDefaultAWSConfig, you can set or override configuration values by setting the fields on the Config struct, such as Region.

cfg.Region = endpoints.UsWest2RegionID

Use the cfg value to provide the loaded configuration to new AWS service clients.

svc := dynamodb.New(cfg)

API request methods

The 2.0 SDK consolidates several ways to make an API call, providing a single request constructor for each API call. This means that your application will create an API request from input parameters, then send it. This enables you to optionally modify and configure how the request will be sent. This includes, but isn’t limited to, modifications such as setting the Context per request, adding request handlers, and enabling logging.

Each API request method is suffixed with Request and returns a typed value for the specific API request.

As an example, to use the Amazon Simple Storage Service GetObject API, the signature of the method is:

func (c *S3) GetObjectRequest(*s3.GetObjectInput) *s3.GetObjectRequest

To use the GetObject API, we pass in the input parameters to the method, just like we would with the 1.x SDK. The 2.0 SDK’s method will initialize a GetObjectRequest value that we can then use to send our request to Amazon S3.

req := svc.GetObjectRequest(params)

// Optionally, set the context or other configuration for the request to use
req.SetContext(ctx)

// Send the request and get the response
resp, err := req.Send()

API enumerations

The 2.0 SDK uses typed enumeration values for all API enumeration fields. This change provides you with the type safety that you and your IDE can leverage to discover which enumeration values are valid for particular fields. Typed enumeration values also provide a stronger type safety story for your application than using string literals directly. The 2.0 SDK uses string aliases for each enumeration type. The SDK also generates typed constants for each enumeration value. This change removes the need for enumeration API fields to be pointers, as a zero-value enumeration always means the field isn’t set.

For example, the Amazon Simple Storage Service PutObject API has a field, ACL ObjectCannedACL. An ObjectCannedACL string alias is defined within the s3 package, and each enumeration value is also defined as a typed constant. In this example, we want to use the typed enumeration values to set an uploaded object to have an ACL of public-read. The constant that the SDK provides for this enumeration value is ObjectCannedACLPublicRead.

svc.PutObjectRequest(&s3.PutObjectInput{
	Bucket: aws.String("myBucket"),
	Key:    aws.String("myKey"),
	ACL:    s3.ObjectCannedACLPublicRead,
	Body:   body,
})

API slice and map elements

The 2.0 SDK removes the need to convert slice and map elements from values to pointers for API calls. This will reduce the overhead of needing to use fields with a type, such as []string, in API calls. The 1.x SDK’s pattern of using pointer types for all slice and map elements was a significant pain point for users, requiring them to convert between the types. The 2.0 SDK does away with the pointer types for slices and maps, using value types instead.

The following example shows how value types for the Amazon Simple Queue Service AddPermission API’s AWSAccountIds and Actions member slices are set.

svc := sqs.New(cfg)

svc.AddPermission(&sqs.AddPermissionInput{
	AWSAcountIds: []string{
		"123456789",
	},
	Actions: []string{
		"SendMessage",
	},

	Label:    aws.String("MessageSender"),
	QueueUrl: aws.String(queueURL)
})

SDK’s use of pointers

We listened to your feedback on the SDK’s significant use of pointers across the surface of the SDK. The Config type was refactored to remove the use of pointers for both Config value and its member fields. Enumeration pointers were removed, and replaced with typed constants. Slice and map elements were also updated to be value types instead of pointers.

The API parameter fields are still pointer types in the 2.0 SDK. We looked at patterns to remove these pointers, changing them to values, but chose not to make a change to the field types. All of the patterns we investigated either didn’t solve the problem fully or imposed an increased risk of unintended API call outcome. For example, unknowingly making an API call with a field type’s zero value required parameters. The 2.0 SDK does include setter’s and utility functions for all API parameter types to provide a workaround to using pointers directly.

Please share your thoughts in GitHub issues or our Gitter channel. We want to hear your feedback.

Giving feedback and contributing

The 2.0 SDK will use GitHub issues to track feature requests and issues with the 2.0 repo. In addition, we’ll use GitHub projects to track large tasks spanning multiple pull requests, such as refactoring the SDK’s internal request lifecycle. You can provide feedback to us in several ways.

GitHub issues. To provide feedback using GitHub issues on the 2.0 repo. This is the preferred mechanism to give feedback so that other users can engage in the conversation, +1 issues, etc. Issues you open will be evaluated, and included in our roadmap for the GA launch.

Gitter channel. For more informal discussions or general feedback, check out our Gitter channel for the 2.0 repo. The Gitter channel is also a great place to ask general questions, and find help to get started with the 2.0 SDK Developer Preview.

Contributing. You can open pull requests for fixes or additions to the AWS SDK for Go 2.0 Developer Preview release. All pull requests must be submitted under the Apache 2.0 license and will be reviewed by an SDK team member before being merged in. Accompanying unit tests, where possible, are appreciated.