The Stream Blog

Go Client Now Available

Go is one of the fastest growing languages around. We ourselves use it extensively inside the Stream API service. Support for Go was added almost two years ago by MrHenry and HyperWorks, which open-sourced a Go client.

We are proud to announce that starting today, we are releasing our official Go API client. You can find it on GitHub at

The new client APIs are more simple and easy to use. Compared to the previous version (which is still available here), the new version has a much smaller code footprint, with about 57% less lines of code. Here’s a list of the key features:

  • Complete test coverage of Stream API endpoints and options
  • Smaller code footprint (less than 900 relevant lines of code)
  • Extensive use of functional options for clearer method calls that, in the future, can be extended without breaking compatibility
  • Utilities for initializing a client directly from environment variables
  • Complete endpoints support
  • Happy Go linter, meaning more consistent docs and idiomatic code
  • Code versioning via

The complete documentation for the client is available via GoDoc, while Stream-specific docs are available on our docs page.

Let’s see how to use it with some simple examples.

Obtaining stream-go2 is straightforward. Type the following to retrieve the latest stable version of the client:
go get

Then, we’ll start by creating a new client which we’ll use in our application:

We can now use the newly created client to initialize the feeds we want to interact with:

Flat, aggregated, and notification feeds implement the stream.Feed interface. To retrieve activities, all of them offer a GetActivities method that returns different structs based on the kind of feed:

Feeds pagination via offset and limit can be done using the WithActivitiesOffset and WithActivitiesLimit option functions:

Pagination via activity ID can be done with the WithActivitiesID[GT,GTE,LT,LTE] functions for the feeds that support it.

Moreover, multiple filters can be combined:

Here are all the supported read options.

If you have a flat feed with custom ranking you can retrieve its’ activities by applying one of the ranking methods configured for that feed with the GetActivitiesWithRanking method:

You can add activities to any kind of stream.Feed with the AddActivity and AddActivities methods:

Removing an activity can be done either by its ID or its foreign ID. The stream.Feed interface offers two methods for doing so: RemoveActivityByID and RemoveActivityByForeignID.

Following and unfollowing a feed is done via the Follow and Unfollow methods offered by the Feed interface:

Note: many methods offered by stream.Feed and stream.Client support variadic option functions to customize the behavior of the methods themselves, and by convention, they all start with the “With…” prefix. You can find them all listed on the GoDoc page.

For example, when using a feed’s GetFollowing method to retrieve the feeds which are being followed, you can use these option functions:

Which results in something like this:

Wrapping up

Once again, we would like to thank MrHenry and HyperWorks for their efforts in creating the original stream-go client, a great community contribution which made it possible for many Go developers to use Stream.

The new Go client exposes all Stream’s API features via a clean and easy to use interface. The client was rewritten from scratch, and this approach allowed us to follow Go’s coding best practices and test the entire code base very easily.

Also published on Medium.