How to Build a Simple API in Rust (Part 2)

June 29th 2021 new story

4

Welcome to the second part of the guide on how to build an API in Rust.

0 reactions

To follow this guide, you will need to have the code from the first part. If you haven’t checked it out yet, please do!

0 reactions

This time I will explain how to connect the API to MongoDB. I will create two endpoints, one to add data to the database and another one to retrieve the data from the database.

0 reactions

I will put all the code in the same file (

src/main.rs

0 reactions

Prerequisites

To be able to follow the guide, you will need to have Rust and Cargo installed. You will also need to have MongoDB running. If you’re not sure how to install MongoDB, there are 3 ways I can think of:

0 reactions

1. You can install MongoDB on your machine. Follow the official documentation to do so.

0 reactions

2. If you have Docker, you can run a MongoDB container. Check out the mongo image documentation. Th.is is the command I use to run the mongo container:

0 reactions

docker run -d -p 27017:27017 --name mongo mongo

3. If you prefer to avoid installing anything (MongoDB/Docker), you can create a free cluster on MongoDB Atlas.

0 reactions

Set up the environment

We need to create a 

.env

.env

.gitignore

.env

0 reactions

Open the project from part 1 and create the 

.env

0 reactions

touch .env

Inside the .env file, add the following:

0 reactions

MONGODB_URI=mongodb://localhost:27017

Make sure to replace the connection string with the correct one depending on how you’re running MongoDB.

0 reactions

It is good practice to have a 

.env.example

.env

0 reactions

Create a .env.example file

0 reactions

touch .env.example

Add the following:

0 reactions

MONGODB_URI= ** MongoDB URI (e.g. mongodb://localhost:27017)

Add the new dependencies

We need to add 2 new dependencies:

dotenv

mongodb

0 reactions

dotenv

0 reactions

mongodb

0 reactions

Update the

Cargo.toml

0 reactions

[dependencies]
tide = "0.16"
async-std = { version = "1", features = ["attributes"] }
serde = { version = "1", features = ["derive"] }
dotenv = "0.15"
mongodb = { version = "1", features = ["async-std-runtime"], default-features = false }

Because we use the

async-std

tokio

async-std-runtime

async-std

0 reactions

Let’s code

We need to make some modifications to the code. First, update the imports with the following:

0 reactions

use async_std::stream::StreamExt;
use dotenv::dotenv;
use mongodb::bson::doc;
use serde::{Deserialize, Serialize};
use std::env;
use tide::{Body, Request, Response, StatusCode};

These are all the module items we will use in this walk-through.

0 reactions

Remember last time we set up an empty Tide

State

State

State

0 reactions

#[derive(Clone)]
struct State {
  db: mongodb::Database,
}

Now we need to update the

main

0 reactions

Here is the updated

main

0 reactions

#[async_std::main]
async fn main() -> tide::Result<()> {
  // Use the dotenv crate to read the .env file and add the environment variables
  dotenv().ok();

  // Create the MongoDB client options with the connection string from the environment variables
  let mongodb_client_options =
    mongodb::options::ClientOptions::parse(&env::var("MONGODB_URI").unwrap()).await?;

  // Instantiate the MongoDB client
  let mongodb_client = mongodb::Client::with_options(mongodb_client_options)?;

  // Get a handle to the "rust-api-example" database
  let db = mongodb_client.database("rust-api-example");

  // Create the Tide state with the database connection
  let state = State { db };

  let mut app = tide::with_state(state);

  app.at("/hello").get(hello);

  app.listen("127.0.0.1:8080").await?;

  return Ok(());
}

I’ve added comments in the code to help you understand what’s going on.

0 reactions

I first called the

dotenv().ok()

.env

State

0 reactions

We will now create two controllers, the first one to create documents in the database and the second one to retrieve those documents.

0 reactions

Here is the code of the first controller:

0 reactions

#[derive(Debug, Serialize, Deserialize)]
// The request's body structure
pub struct Item {
  pub name: String,
  pub price: f32,
}

async fn post_item(mut req: Request<State>) -> tide::Result {
  // Read the request's body and transform it into a struct
  let item = req.body_json::<Item>().await?;

  // Recover the database connection handle from the Tide state
  let db = &req.state().db;

  // Get a handle to the "items" collection
  let items_collection = db.collection_with_type::<Item>("items");

  // Insert a new Item in the "items" collection using values
  // from the request's body
  items_collection
    .insert_one(
      Item {
        name: item.name,
        price: item.price,
      },
      None,
    )
    .await?;

  // Return 200 if everything went fine
  return Ok(Response::new(StatusCode::Ok));
}

First, I’ve defined an

Item

name

string

price

number

0 reactions

Inside the function, I first try to read the request’s body. I did not do any validation. In a real case, don’t be like me and always validate the request’s body before using it.

0 reactions

I recover the database connection from the Tide

State

items

0 reactions

Finally, I attempt to insert a new document in the collection using the request’s body values.

0 reactions

If everything goes smoothly, I return an HTTP status code 200.

0 reactions

Now let’s create a second controller to retrieve documents from the

items

0 reactions

async fn get_items(req: Request<State>) -> tide::Result<tide::Body> {
  // Recover the database connection handle from the Tide state
  let db = &req.state().db;

  // Get a handle to the "items" collection
  let items_collection = db.collection_with_type::<Item>("items");

  // Find all the documents from the "items" collection
  let mut cursor = items_collection.find(None, None).await?;

  // Create a new empty Vector of Item
  let mut data = Vec::<Item>::new();

  // Loop through the results of the find query
  while let Some(result) = cursor.next().await {
    // If the result is ok, add the Item in the Vector
    if let Ok(item) = result {
      data.push(item);
    }
  }

  // Send the response with the list of items
  return Body::from_json(&data);
}

Inside the function, I retrieve the handle to the database connection from the Tide

State

items

0 reactions

I use the

find

items

0 reactions

I loop through the

find

item

0 reactions

Finally, I send the response with the list of items in the body.

0 reactions

The controllers are ready, but we still need to add them to the

main

hello

main

0 reactions

app.at("/items").get(get_items);
app.at("/items").post(post_item);

Voilà! Let’s test it out. Start the server with the following command:

0 reactions

cargo run

You should now be able to send a

POST

/items

Content-Type

application/json

0 reactions

{
  "name": "coffee",
  "price": 2.5
}

You should get an empty response with status code 200.

0 reactions

Then try to retrieve the document you just created by doing a

GET

/items

0 reactions

You should receive an array with a single entry being the item we just created

0 reactions

[
  {
    "name": "coffee",
    "price": 2.5
  }
]

Conclusion

That’s it for part two of this guide. I hope it was helpful. If you noticed any errors or something that could be improved, please let me know!

0 reactions

You can find the full example on GitHub: https://github.com/ncribt/rust-api-example-part-2.

0 reactions

In the next and last part of the guide, I will show you how to protect the POST /items endpoint using a JWT (JSON Web Token) and a middleware.

0 reactions

Previously published on https://naruhodo.dev/build-an-api-in-rust-part-2/.

0 reactions

4