Dirt Simple Web Service using Rust

In my continuing education of learning Rust, I wanted to create a simple web service that returned json using the Actix web framework. So I searched the web for a good tutorial but they were all very complicated.

So I cobbled together one using the Actix examples and from the documentation.

The source code can be found at:

Simple Rust Web Service

Prerequisites

I will assume that you have the Rust toolchain installed and that’s about it other than some basic HTML knowledge. You should be comfortable using the rust Cargo tool to create, build and run projects.

Definitions

1. Web Service — A web service is a collection of open protocols and standards used for exchanging data between applications or systems.

2. REST — Representational state transfer (REST) is a software architectural style that was created to guide the design and development of the architecture for the World Wide Web.

3. JSON — JSON stands for J ava S cript O bject N otation. JSON is a lightweight format for storing and transporting data.

4. CORS — Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources on a web page to be requested from another domain outside the domain from which the first resource was served.

Data

The data we will be transmitting via our web service is car data in JSON format. An example is below:

Functional and Design requirements

1. Initial Coding — At first we will just return a hard coded json record.
2. Structures — We will use the structures below to hold our car data then use the Serde crate to serialize and de-serialize our structures.

3. Route — Our initial route will look like http://127.0.0.1:9100/cars/Acura This will change when we add a query mechanism.

4. Query Route — After our first initial test, we will add a query mechanism. The route will look like: http://127.0.0.1:9100/cars/Acura/2003/make:eq,first_year:gte. This will return json that has all cars of make Acura with first year of production greater than or equal to 2003.

5. Car service client — We will create a http server in Actix that will serve a static page that will consume our web service.

Initial Web Service

Open up a terminal session and run the command below. This will create our project.

Change directories to the cars_service directory and fire up your text editor to make the changes to the cargo.toml file as shown below:

Change directories to cars_service/src and cut and paste the following in main.rs:

Change back to the cars_service directory and build your project using the cargo build command. This will take about 10 minutes so go get a coffee and talk to your cube mate.

Finally from the terminal issue the cargo run command and you should see the following:

Now open another terminal window and issue the following curl command:

Voila! our web service has returned back json!

Initial Code Review

Let’s review the code and some important concepts.

1. Our get_cars function is used to parse the route parameters and return the json data.

2. Our main function create an App instance and registers our get_cars function with the Http Server.

3. IMPORTANT — We wrap a Cors::permissive() call with the App to use during development . You should never do this in production. Use Cors::default() and only add the protocols and permissible users(ip’s) as needed.

4. We use a Actix Rust attribute to create the route for our get_cars function:

#[get(“/cars/{car}”)]

Adding Querying Capability To Web Service

We will now add querying capability to the web service. A querying url would look like:

http://127.0.0.1:9100/cars/Acura/2003/make:eq,first_year:gte

We will change the route attribute in main.rs from:

#[get(“/cars/{car}”)]

To:

#[get(“/cars/{car}/{first_year}/{query}”)]

All of our car makes and models will reside in a cars.json file which we will query using Rust’s matching functionality.

New main.rs

The source code for the new main.rs is shown below:

Cut and paste the above in your main.rs in the cars_service project, and in a terminal session in the cars_service directory run the cargo run command.

In another terminal session enter the following curl command:

curl -G http://127.0.0.1:9100/cars/Acura/2003/make:eq,first_year:gte -w “\n”

You will see the following output:

Final Code Review

1. We will query cars.json file to get our car records.
2. Our new GET route contains car, first_year and query parameters.
3. We open the json file, use Serde to de-serialize it to a CarList structure.
4. We pass the CarList and the CarQuery to our query function, get_query it will return a Vec of Car structures.
5. The returned Vec is serialized to json and returned to the calling client. In our case, curl.

Concluding Remarks

The source code for the web service above and an actix cars client can be found at: Simple Rust Web Service. Check out the readme for instructions for running the service and client.

This web service is by no means ready for prime time but I hope it gives you the nucleus for designing a production ready micro web service using the awesome web framework Actix and the great language of Rust.