Introduction to the REST API

Hello there, and welcome to Stream's REST API documentation!

Please note

The REST documentation is recommended for advanced users that want to write their own API clients. Have a look below at the official clients, framework integrations, and community-contributed libraries.

Always feel free to get in touch at support@getstream.io if you have questions.

Are you looking for a ready-made client or framework library?

If you're looking to get started quickly - official clients are available for a whole host of languages including Ruby, JavaScript, Python, PHP, and more.

Framework integrations are also available for Rails, Django, Laravel, and Meteor - in addition to community-contributed libraries for Go, .NET, and Scala.

First steps

1. Complete 'Getting Started'

Before you start writing your client we recommend that you give the getting started a try. It explains the core API concepts, and allows you to get you familiar with Stream.

2. Review Official Clients

Reviewing the official Stream API clients is a great source of inspiration for writing your own client.

A good starting point is the official JavaScript client as it runs its test suite in the browser.

With the official JS client, you can see the tests and have a look at how the API requests are structured in your browser's network tab.

To see the tests, simply clone the stream-js package, and open test/browser/test.html in your browser.

You can review any library or framework over at the official Stream GitHub page.

3. Browse Documentation

Stream's API consists of two authentication methods and eight REST endpoints. Be sure to review the basics.

Authentication Methods:

  • Application
  • Feed

REST Endpoints:

  • Activities
  • Feed
  • Feed Detail
  • Followers
  • Following
  • Following Detail
  • Batch Activity Add
  • Batch Follow

Get stuck? No worries at all - feel free to contact support at any time.

Basics

Base API URL:
https://api.getstream.io/api/v1.0/

Location Support

The Stream API is currently available in 3 regions:

  • us-east
  • us-west
  • eu-west

Examples:

https://us-east-api.getstream.io/api/v1.0/

https://us-west-api.getstream.io/api/v1.0/

https://eu-west-api.getstream.io/api/v1.0/

Common Parameters

The following common GET parameters should be sent for every request:

Name Type Description
api_key string The API Key

Note: Every request should also include the appropriate authorization header.

JSON for POST Data

All POST data should be JSON encoded. This allows you to send complex data structures to the Stream API endpoint!

Authentication

Depending on the resource being requested, Stream uses one of two authentication methods:

Both authentication methods create a signature that is specific to the requested resource (feed, or application).

When dealing with authentication tokens, you should keep in mind that tokens are passwords. Never share tokens with untrusted parties.

Feed Authentication

Requests to the Stream API specific to a single feed use Feed Authentication to authenticate requests.

JSON Web Tokens (JWT)

This authentication method uses JSON Web Tokens (JWT) to authenticate requests. This is a standardized method to give permissions by signing a JSON formatted token with a secret key. Read more about JWT at jwt.io/introduction.

The great news is that libraries are available in many languages for encoding and decoding JSON Web Tokens. Have a look at the jwt.io libraries page to see if your language of choice is supported. And yes, a Delphi library is available.

JWT usage for feed authentication

For feed authentication the client should send a token that is signed with the secret of the app. This token must include a permission scope compatible to the request that is being performed. Permission scopes are defined using the following fields: resource, action and feed_id.

The resource field of the JWT payload allows you to define which API endpoints can be accessed, you can pick one of the following:

The action field of the JWT payload allows you to define which HTTP verbs are allowed by a request:

The feed_id field in the JWT payload specifies for which feed the permissions specified before are granted. The value of this field should be a concatenation of the feed group's slug and the user_id of the feed instance (eg."news1234). Similarly to the resource and action field a single * character will grant the permissions on all feeds.

Sending an authenticated request

Once the token is generated correctly it still needs to be used to authenticate a request. This is done by seting two HTTP headers on the request:

  1. Stream-Auth-Type: jwt
  2. Authorization: <token>

Important: Some of the JWT libraries prefix the generated token with the string "Bearer". This prefix should be removed before sending the request.

Token examples

Below are some example tokens for different use cases:

// A token which allows every possible action on all feeds. Useful for
// development and server side, but unsuitable for usage on the client.
{
    "resource": "*",
    "action": "*",
    "feed_id": "*"

}

// A token which allows reading, modification and deletion of activities on
// the feed of the user with id 123.
{
    "resource": "feed",
    "action": "*",
    "feed_id": "user123"

}

// A token which allows reading the followers of the feed of user with id 123.
{
    "resource": "follower",
    "action": "read",
    "feed_id": "user123"

}

Application Authentication

When you are performing actions that are not specific to a single feed (such as application configuration, or batching), Application Authentication is used.

IETF: "Signing HTTP Messages"

Stream's Application Authentication implementation is based on the "Signing HTTP Messages" IETF Draft v3.

In order to authenticate, you need to send the HTTP Headers as indicated by the IETF Draft, as well as the X-Api-Key HTTP header containing your application's API key.

    `X-Api-Key: api_key`
  
Endpoint: Activities
The activities endpoint is located at
activities/
Authentication method: Feed Authentication
Resource Name:  activities

The Activities endpoint can be used to update activity data stored by Stream API.

This is useful when you want to update certain activity metadata used during feed ranking. Activities are updated by foreign_id. Changing the time property of the activity is not allowed.


POST

Name Type Description Default
list A JSON encoded list of activities to update. Maximum length is 100.

Endpoint: Feed

The feed endpoint is located at
feed/(feed_slug)/(user_id)/
Authentication method: Feed Authentication
Resource Name:  feed

The Feed endpoint is to retrieve activities in a feed (GET), or to submit an activity or list of activities (POST).

GET

For retrieving the activities in a feed the following parameters as shown below are supported. Note: The id_lte pagination type is preferable to the traditional offset approach.

Name Type Description Default Optional
limit int The amount of activities requested from the APIs 25
id_gte int Filter the feed on ids greater than or equal to the given value
id_gt int Filter the feed on ids greater than the given value
id_lte int Filter the feed on ids smaller than or equal to the given value
id_lt int Filter the feed on ids smaller than the given value
offset int The offset 0

If ranking is enabled on your feed group you can supply the ranking method to use by supplying the ranking method's slug on the following GET parameter:

Name Type Description Default Optional
ranking string The slug of the ranking method to use

POST

For the POST request, you can either submit the data for one single activity or a list of activities. In addition to these base fields, extra data will be parsed as custom fields.

Name Type Description Default Optional
actor string The actor performing the activity
verb string The verb of the activity
object string The object of the activity
target string The optional target of the activity
time string The optional time of the activity, isoformat Current time
to list See the documentation on Targeting & "TO" support.
foreign_id string A unique ID from your application for this activity. IE: pin:1 or like:300

When you are sending a list of activities, the parameters are:

Name Type Description
activities list A JSON encoded list of activity data. The data for individual activities is the same as specified above.

Endpoint: Feed Detail

The feed detail endpoint is located at
feed/(feed_slug)/(user_id)/(activity_id|foreign_id)/
Authentication method: Feed Authentication
Resource Name:  feed

The Feed Detail endpoint allows you to delete activities. The Stream API allows you to delete activities by their activity id or foreign id:

  • The activity id is returned to you in the response when the activity is first created.
  • The foreign id is a unique reference which represents the activity in your database.

Note: By setting foreign ids you ensure uniqueness and no longer need to store the response-based activity id in your database. Read more about foreign ids versus activity ids over at the Stream general docs.

DELETE

Note: Deleting by foreign id requires setting a foreign_id URL query parameter to "1":

Name Type Description Optional
foreign_id string Send a value of 1 to indicate you want to delete by foreign id

Endpoint: Followers

The followers endpoint is located at
feed/(feed_slug)/(user_id)/followers/
Authentication method: Feed Authentication
Resource Name:  follower

The Followers endpoint is used to retrieve a paginated list of the given feed's followers. The resource is limited to the most recent 500 results.

GET

Name Type Description Default Optional
limit int The amount of feeds following this feed requested from the APIs 25
offset int The offset, max 400 0

Endpoint: Following

The following endpoint is located at
feed/(feed_slug)/(user_id)/following/
Authentication method: Feed Authentication
Resource Name:  follower

The Following endpoint is for retrieving a list of feeds that are following the feed (GET), or to follow a target feed (POST). The resource is limited to the most recent 500 results.

GET

Returns a paginated list of the feeds which are following the feed.

Name Type Description Default Optional
limit int The amount of followed feeds requested from the APIs 25
offset int The offset, max 400 0
filter string List of comma separated feed ids to filter on. IE user:1,user:2. Allows you to check if a certain feed is followed.

POST

Follows a target feed.
Name Type Description Default Optional
target string The target feed this feed should follow. For example user:44.
activity_copy_limit integer How many activities should be copied from the target feed, max 1000 300

Endpoint: Following Detail

The following detail endpoint is located at
feed/(feed_slug)/(user_id)/following/(target)/
Authentication method: Feed Authentication
Resource Name:  follower

The Following Detail endpoint allows you to unfollow a target feed.

DELETE

Name Type Description Default Optional
keep_history string When provided the activities from target feed will not be kept in the feed

Target is in the syntax of [feed]:[id]. For example, "user:1".

Note: Unfollow target's activities are purged from the feed unless the keep_history parameter is provided.

Endpoint: Batch Activity Add

The batch follow endpoint is located at
feed/add_to_many/
Authentication method: Application Authentication

The Batch Activity Add endpoint allows you to add an activity to multiple feeds in one single request.

POST

Name Type Description
feeds list The list of feeds where the activity will be stored eg. ['user:1', 'flat:2' ]
activity object A JSON encoded activity object (see feed endpoint for reference)

Endpoint: Batch Follow

The batch follow endpoint is located at
follow_many/
Authentication method: Application Authentication

The Batch Follow endpoint allows you to create multiple follows in one single batch request.

POST

Note: The `activity_copy_limit` parameter is a query parameter.

Name Type Description Default Optional
list A JSON encoded list of a follow object {'source': 'source:id', 'target': 'target:id'} . eg. [{'source': 'flat:1', 'target': 'user:2'}, ]
activity_copy_limit integer How many activities should be copied from the target feed, max 1000 300

Options

All clients should support several options:

API Location (Region)

Location/Region should be configurable when initializing the Stream client.

Request Timeout

The request timeout should be configurable. We recommend 3 seconds as a default.

On average, it takes ~60ms to retrieve your feed. However, it is possible for network latency to spike, which is why we recommend setting a timeout.

Best Practices

Here's a brief list of good practices that we totally recommend:

Test Code Coverage (>95%)

We recommend running integration tests, ensuring a code coverage above 95%.

Code Examples - Every API Endpoint

It's good to document the API calls for every operation.

Check out the README of the stream-python repo for a good starting point.

Input Validation

Feed slugs and user ids need to match the \w+ regular expression. Your client should validate input before sending the call.

Error Mapping

Errors from the Stream API should be mapped to exception classes and properly raised.

Naming Standards

We try to keep our variable names consistent amongst the various API clients. This section explains some common terminology.