Getting started and integrating with a technical solution, like Stream, can be exciting. Sometimes you just want to rip open the proverbial box and get started. When implementing a new API I rarely want to read pages and pages of (sometimes boring) documentation — so here’s your TL;DR version of the 5 things you need to know to get started quickly and effectively using Stream.
Ready, set, go!
- When inserting an activity, send both the foreign_id AND time fields. Send a UUID (or other unique value) for the foreign_id, and grab the current time. Doing this will ensure you have unique criteria for the record. If you don’t do this, you won’t be able to update that activity later. Having both those fields is what ensures that activity is unique You can think of it like a multicolumn primary key. — so you also don’t run into a copy under the hood situation, or duplicates in your feed.
- Use id_lte instead of offset for pagination. The activities in the feed are sorted against a UUID based on time. We recommend you paginate using
id_lt. This performs far better than traditional offset based pagination. - Do not send PII. We recommend sending user IDs instead of personal information, and when you pull the feed back do a quick array translation. It’s always a good idea to err on the side of caution when dealing with the storage of personal information, but don’t let this scare you though. We have very successful customers whose apps contain sensitive information like location, or even tightly (HIPAA) controlled health information like heart rate from wearable IoT.
- Keep activity size under 1k. While we allow you to add any custom fields to activities JSON package, if the size goes beyond 1k then performance can be impacted. We often get questions from customers about attaching images, videos, etc to the activities. or media. Use a reference to a location where your media is stored, and enrich it on your backend after you’ve done the read from us.
- Remember that fan-out only goes 1 level deep. When you add an activity, it is automatically updated in all the feeds that follow that feed, but not another level deep. For example: if Feed C follows Feed B which follows Feed A (C->B->A), adding an activity to Feed A will automatically fan out to Feed B. Feed C will not get that update unless you add it in the TO field. (Though do note the limit for the TO field is 100 feeds.)
Planning for the above in the early stages can help you avoid surprises and cost overruns down the road.
If you haven’t done so already, but sure to check out Stream’s documentation for other useful tips and tricks.
And just for fun…
This is a collaboration from the team at GetStream.io, led by David Stillman, Software Engineer. The original blog post can be found at https://getstream.io/blog/5-common-mistakes-integrating-stream-api/.