Intro
Building an easy-to-use API is hard, but onboarding shouldn’t be. It’s important that we, at Stream, make the onboarding experience as painless as possible for developers. Many of you have told us that our 5 minute interactive API tutorial helped you to quickly understand Stream's API. Today, we wanted to announce that we’ve made our tutorial even faster and easier to understand. I run design over at Stream and wanted to share some of our thinking behind this experience:
What’s the “Getting Started”?
Our “Getting Started” is a self-driving demo that shows you, in as few words possible, what you can make with Stream. It focuses on the core parts of Stream so you can begin to imagine how it can fit your unique use case. The “Getting Started” lets you hit the Stream API directly, with clear and editable code examples.
How does it work?
We wanted to make the reading experience smooth and natural. This led us to lean on a two column setup. On the left, we include the tutorial content (01.a and 01.b) with an example feed structure on the right (02). This allows you to read the information and see the context of the code and UI together.
Each code section has a “Run JS” command in it. As you click that, the example UI will refresh. You can follow the tutorial with any of our client libraries. By default we show Javascript, but you can follow along with Ruby, PHP, Python, GO, Java or .NET. The UI listens to changes in real-time so you can use your shell to run these commands as well.
Get your API Key
Since you get to work directly with the API, you'll need to register to get an API key. The login with Github makes it very easy to get started.
Working with Flat Feeds
We start the tutorial off with Flat Feeds. Flat is our default feed type and the only feed type that can be followed by other feeds. The first part of this tutorial is about building follows and posting some activities/tweets. For activities, we follow the activity stream spec.
Follows
Feeds are still the best way to surface content on a platform. Allowing users to follow feeds is important and basic to many apps and websites. In this step, we show you how easy it is for a user to follow another user feed. Our API gives you complete control over the User Experience. In this example, you’ll see that real-time updates are displayed on the right side of the screen as you take the actions outlined in each step of the tutorial. For example, Tweets Eric writes will show up on Jessica’s flat feed. The example teaches you how to follow users, but you could easily apply the same API calls for following songs, playlists, matches, topics etc.
Aggregated Feeds
One of the common use cases for Stream is building a feed like Facebook. Our Aggregated Feed allows you to set up aggregation rules for your feeds. In this part of the Tutorial, we show a very basic rule format of verb and day. Although this is a more advanced feature, we wanted to highlight some of the more powerful capabilities of Stream.
In the example above, we are able to show activities that have been grouped together. If a user has liked 40 images, you can use Aggregated Feeds to show the two most recently liked images and then display “38 others” next to it. Here is an example of an Aggregated Feed from Instagram:
Real-Time
In the last part of our interactive tutorial, we show another advanced feature. Using our realtime API, you can listen to feed changes. (This example uses websockets, you can also listen to a Firehose of activities via SQS or webhooks) Note: To receive real-time notifications for a feed, you need to enable the feature via the Dashboard's feed configuration page.
Next Steps
We hope that completing this revamped, interactive tutorial will help you get a good idea of what you can do with Stream, and that this post gives you some insight as to our desired user experience for developers. If you didn't do so before, now is a good time to try out our 5m interactive onboarding experience. We do our best to make our activity streams as easy to use as possible. Contact us to share your thoughts on how we can make it easier to get started with Stream.
P.S.
If you would like to check out some other resources that are useful for onboarding, here are a few I recommend: