Open Source REST API for Chat with Express, MongoDB, and Heroku
Tags: api, rest, tutorial, node
Published: 2020-01-09 03:40:44

## Overview

Here at [Stream](https://getstream.io/), we’re known for our Feeds as a Service as well as our Chat as a Service product. [Stream Chat](https://getstream.io/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](https://www.npmjs.com/package/stream-chat) 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](https://github.com/nparsons08/stream-chat-api). 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](https://kubernetes.io/) for scalability._

## Support

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
* Heavily commented modern JavaScript

## 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](https://medium.com/better-programming/best-practices-for-versioning-an-api-for-rest-apis-530a9398f311)” 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 `controllers` and `utils` within the `src` directory. Our `package.json` scripts make use of Babel to transpile ES6 into ES5 JavaScript so that it can run on the server. You will also notice that inside of the `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 git@github.com: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 `.env.example`.

For example:

`cd stream-chat-api && touch .env`

Then, open `.env` and add the following environment variables:

https://gist.github.com/nparsons08/705022fea062a055e19451b49005b4fd

> **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._

https://gist.github.com/nparsons08/bb2d8a886eee9edbe482f8e73bc34bd8

## 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. 

<p>
  <a href="https://heroku.com/deploy?template=https://github.com/nparsons08/stream-chat-api" target="_blank" rel="noopener noreferrer">
    <img src="https://www.herokucdn.com/deploy/button.svg" alt="Deploy">
  </a>
</p>

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).

![](https://stream-blog-v2.imgix.net/blog/wp-content/uploads/6d5c740682f0a0c4e9c62c10dd1e41ba/image2.png?auto=compress%2Cformat&ixlib=php-1.2.1)

## 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:

https://gist.github.com/nparsons08/adb472bf1bcaf9a256aac1586e551f1a

Using the REST API client Postman, you can quickly test the API as shown in the screenshots below:

![](https://stream-blog-v2.imgix.net/blog/wp-content/uploads/982de993623aa23421e223599a664248/image1.png?auto=compress%2Cformat&ixlib=php-1.2.1)

![](https://stream-blog-v2.imgix.net/blog/wp-content/uploads/4cb450b7e8e9ee04ad75e3b1ab7d94fe/image3.png?auto=compress%2Cformat&ixlib=php-1.2.1)

> **Note**: _The `POST` URL is versioned to `v1` making the initial URL path `v1/auth/init`._

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](https://getstream.io/chat/).

Happy coding! 🤓