•January 8th 2020
Here at Stream, we’re known for our Feeds as a Service as well as our Chat as a Service product. Stream Chat was released out of beta late last year, and we’ve been receiving quite a few inquiries on how to structure a RESTful API to support the backend portion of chat. The backend is quite simple as it only requires that you generate a JWT token for a user to use on the frontend side of your application.
However, there is a lot more than you can do with the Stream's Chat JS SDK than generating a JWT token – you can add users to channels, send and remove messages, ban users, create channels, etc. In this post, I’ll outline how I built a REST API using Express – and best of all, it’s scalable so that you can continue to build additional functionality to support your application further.
Note: The repository is fully open-source and can be found on GitHub. There are detailed instructions on not only deploying to Heroku, but there is also support for Docker should you want to containerize your application and deploy on something like Kubernetes for scalability.
The REST API for Stream Chat supports the following:
- User storage via MongoDB database
- Mongoose schema with validation for user profiles
- Password validation and hashing with bcrypt
- Find or create for users within the MongoDB database
- Easy deployment to Heroku (optional) or any other environment
- Token generation for existing and new users (for Stream Chat)
- Creation of a new channel named “General” if one does not exist
- Automatic adding of users to the “General” channel
Basic API Anatomy
The API is rather basic and provides built-in support for versioning your API should you need to make changes down the road. For more information on my opinion on API versioning, have a look at my post titled “Best Practices for Versioning REST APIs” on Medium.
The layout of the API is rather simple. The starting point is
index.js as per usual, and there are directories for
routes as well as
utils within the
src directory. Our
controllers directory, there are directories for the versions. This is what allows for API versioning, as I mentioned above.
Cloning & Customizing the API
To clone the API, simply run
git clone firstname.lastname@example.org:nparsons08/stream-chat-api.git. Then, you’ll want to ensure that you create a
.env file and fill it in with the credentials as shown in
cd stream-chat-api && touch .env
.env and add the following environment variables:
Note: Creating an account on Stream is free, and you can do so at https://getstream.io. Once your account is created, you can capture your API key and secret on the dashboard. Additionally, a MongoDB instance/cluster is required for this API to function properly – I recommend MongoDB Atlas, which offers a 100% free cluster in multiple regions. Documentation on getting started with MongoDB Atlas is located here.
Deploying to Heroku
If you are deploying to Heroku, you can use the one-click Heroku Deploy button below and fill in the environment variables on the setup screen.
Alternatively, you can create a new application and push your repository to Heroku (note that you will have to manually configure environment variables if you go about using a manual push method – environment variables can be configured under the settings).
Sending Your Payload
The API (as-is) expects that you send it a specific payload to create a user and add them to a channel. To do this, send a
POST request with the content type set to
application/json using the following payload:
Using the REST API client Postman, you can quickly test the API as shown in the screenshots below:
POSTURL is versioned to
v1making the initial URL path
And that’s it! You’ve successfully set up an API specifically for Stream Chat. The API is fully customizable and is prepared to suit any needs you may encounter while building a REST API for Stream Chat.
Happy coding! 🤓