linodego Go Client Library

The client internals have migrated from Resty to net/http. If you use advanced hooks or custom error handling, you must update your implementation.

Observable changes:

• Request now maps to *http.Request.
• Response now maps to *http.Response.
• The Logger is now a local interface, not Resty's logger.
• OnBeforeRequest and OnAfterResponse hooks now use *http.Request and *http.Response.
• Retry logic: Retry condition and retry-after callback types now use *http.Response. Retry helper names are now exported (capitalized).
• Error handling: Error handling is now centered around http.Response instead of Resty responses.

Linode API calls are often asynchronous. linodego provides two primary ways to wait for completion:

1. Status Polling: Use WaitFor*Status helpers when you care if a resource has reached a specific state (e.g., an instance is running).
2. Event Polling: Use EventPoller when you care about a specific action completing (e.g., a linode_boot action reaches finished).

Rule of thumb:

• Use status waits to check if a resource looks ready.
• Use event waits to check if a particular action completed.
• Prefer EventPoller over WaitForEventFinished if you can instantiate the poller before triggering the mutating API call.

Linodego v2 performs significant cleanup of pointer-heavy types. You should audit your code for the following patterns:

1. Slice pointer changes: Many types have changed from pointer slices to value slices (e.g., []*T $\rightarrow$ []T or *[]string $\rightarrow$ []string).
2. Nullability: Some string fields have become pointers to support nullable semantics.
3. Payload splits: Create and Update types have been split for request payloads.
4. JSON Semantics: A large number of JSON tags changed from omitempty to omitzero. This affects how you distinguish between "clearing" a field and "omitting" it. Run integration tests to validate update behavior.

Review areas:

• Code relying on nil checks.
• Code relying on pointer identity.
• Code distinguishing between "unset" and "empty".
• Mutation of shared slices.

Wait helpers (like WaitForFinished or WaitForInstanceStatus) can block indefinitely if the expected state is never reached. Always pass a deadline-aware context.Context to the wait call. When the context expires, the helper returns an error containing ctx.Err().

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
defer cancel()

instance, err := client.WaitForInstanceStatus(ctx, instanceID, linodego.InstanceRunning)
if err != nil {
	log.Fatal(err)
}

When creating a resource, the ID is unknown until the call returns. Use NewEventPollerWithoutEntity to create a poller that doesn't snapshot existing events.

Important: You must set the poller.EntityID field immediately after receiving the new resource ID and before calling WaitForFinished.

poller, err := client.NewEventPollerWithoutEntity(
	linodego.EntityLinode,
	linodego.ActionLinodeCreate,
)
if err != nil {
	log.Fatal(err)
}

instance, err := client.CreateInstance(ctx, linodego.InstanceCreateOptions{
	Region: "us-east",
	Type:   "g6-nanode-1",
	Label:  "create-poll-example",
	Booted: linodego.Pointer(false),
})
if err != nil {
	log.Fatal(err)
}

// Set this before waiting.
poller.EntityID = instance.ID

event, err := poller.WaitForFinished(ctx)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("create event %d finished\n", event.ID)

The project uses make for testing tasks:

• make test-unit: Runs unit tests.
• make test-int: Runs integration tests (uses fixtures).
• make fixtures: Records new API responses into the fixtures/ directory.

Warning: When running make fixtures, be careful not to commit sensitive account details. While some sanitization is attempted, fixtures/*Account*.yaml files are not automatically sanitized. To target a specific test for fixture updates, use: make TEST_ARGS="-run TestName" fixtures.

make test-unit
make test-int
make fixtures
make TEST_ARGS="-run TestListVolumes" fixtures

To install the linodego v2 client, use the following Go command:

go get -u github.com/linode/linodego/v2

Object Storage APIs have moved from cluster-oriented naming to region-based usage.

Key changes:

• Stop using ObjectStorageBucket.Cluster.
• Use region IDs in all bucket, object, cert, and ACL calls.
• Replace ListObjectStorageBucketsInCluster with ListObjectStorageBucketsInRegion.
• Remove usage of deleted ObjectStorageCluster APIs.
• Access Management: GetObjectStorageBucketAccess now returns the new access shape directly (no separate V2 type needed). UpdateObjectStorageBucketAccess now uses PUT, and ModifyObjectStorageBucketAccess is a new POST method.
• Compatibility: Remove any temporary V2-suffixed Object Storage APIs and use the supported non-V2 names.