A Rusty Web Service 🦀

HTTP Endpoint With Actix

Hello World 👋

To start with, we can make a service that runs and responds with a static message on a single HTTP endpoint.

After creating the project with cargo new we need to add a depencency on Actix to our cargo.toml file:

[dependencies]
actix-web = "3"

Then we need to replace the code in main.rs with a function to handle our sample endpoint, and appropriate config to run the Actix HttpServer:

use actix_web::{web, App, HttpResponse, HttpServer};

fn hello_world() -> HttpResponse {
    HttpResponse::Ok().body("hi! 👋")
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(move || App::new().route("hello", web::get().to(hello_world)))
        .bind("0.0.0.0:8000")?
        .run()
        .await
}

The hello_world() function returns a 200 OK http response with a simple text message in the body.

The main() function runs a new http server on port 8000, and binds the hello_world() function to the path /hello.

We can quickly test this by running the server using cargo run and making a request locally:

GET http://localhost:8000/hello

hi! 👋
// GET http://localhost:8000/hello
// HTTP/1.1 200 OK
// content-length: 8

POSTing Data 📬

Just returning static data isn't very useful - we need to be able to receive data from a client and then do something with it. To do that, we'll make a POST endpoint that can deserialize JSON into a type that we'll define.

The data we receive should be identifiable, so it will have an id property that we will use a Uuid for, as well as some other data that we can store in Strings:

pub struct SampleData {
    id: Uuid,
    name: String,
    special_code: String
}

In order to use Uuid we need to add a dependency on the uuid crate. We also need to make this type (de)serializable and Serde seems to be the standard choice for that in Rust. Both should be added to the cargo.toml file as dependencies alongside actix-web:

[dependencies]
uuid = { version = "0.8", features = ["serde"] }
serde = "1.0.126"

Cargo dependencies have a neat option to have different features toggled on or off when they're included in the cargo.toml file - here we make use of it to toggle on the serde bindings that are provided by the Uuid crate 😍

With the dependencies in place, we can automatically derive the traits needed for serialization of our type:

use serde::{Deserialize, Serialize};
use uuid::Uuid;

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(rename_all = "camelCase")]
pub struct SampleData {
    id: Uuid,
    name: String,
    special_code: String
}

The extra serde attribute handles translating property names between snake_case in our rust code and camelCase which is more common in JSON.

With the data type in place, we can add an endpoint to the application that will receive this data as JSON. Actix uses Extractors to handle deserialization automatically using the serde traits that we have already derived for our type. If deserialization fails, it will return a 400 Bad Request, otherwise it will pass the deserialized value to our handler function. That makes it very straightforward for us to add an endpoint that receives the data and returns the id for it as a small check that everything is working as we expect.

The handler function is defined:

fn receive_data(sample: web::Json<SampleData>) -> HttpResponse {
    HttpResponse::Ok().body(sample.id.to_hyphenated().to_string())
}

And then added to the HttpServer in the main function:

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(move || {
        App::new()
            .route("hello", web::get().to(hello_world))
            .route("data", web::post().to(receive_data))
    })
    .bind("0.0.0.0:8000")?
    .run()
    .await
}

This is also quick to test using cargo run and making a request against the service:

POST http://localhost:8000/data
Content-Type: application/json

{
  "id": "82115a42-3b60-4adf-b7c8-6a5afe73bc58",
  "name": "test",
  "specialCode": "1234"
}

82115a42-3b60-4adf-b7c8-6a5afe73bc58
// POST http://localhost:8000/data
// HTTP/1.1 200 OK
// content-length: 36

Logging 🪵

When the service is deployed and being used, it would be useful to have it log some information so we could monitor if everything was running as expected. We can start very simply by printing messages when the service starts and stops so we get some output to tell us that it's running:

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    println!("🧑‍🔬 Sample Service Starting");

    let result = HttpServer::new(move || {
        App::new()
            .route("hello", web::get().to(hello_world))
            .route("data", web::post().to(receive_data))
    })
    .bind("0.0.0.0:8000")?
    .run()
    .await;

    println!("🧑‍🔬 Sample Service Stopping");

    result
}

Note how we now assign the result of running the HttpServer to a value so that we can print a message just before the service terminates.

This gives us an idea that the service started (or stopped), but it doesn't provide any information about what happens while the service is running - fortunately we can provide Actix with a Logger and it will log information about each request. Actix uses Middleware to implement logging, and we can pass it any log implementation that is compatible with the log crate facade. There are sensible logging options to choose from, but for this service we'll use the much more interesting emoji-logger 😀

To set up the logger we first add a dependency in cargo.toml:

[dependencies]
emoji-logger = "0.1.0"

Reference the crate with extern crate emoji_logger; at the top of main.rs and then initialise it in the main() function using emoji_logger::init();. This will create the logger, but we still need to configure Actix to use it by passing one or more Loggers with the format we want. We can also provide an environment variable to configure the level of log messages that are output - for now we can set that in code, but later we should read that from the environment so that it's easy to configure between different environments (for example, we might want to output a lot of data when running locally, but find that would be too spammy when the service is running in production).

With our logger initialised and configured with Actix we now have the following code:

use actix_web::{App, HttpResponse, HttpServer, middleware::Logger, web};

extern crate emoji_logger;

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    println!("🧑‍🔬 Sample Service Starting");

    std::env::set_var("RUST_LOG", "actix_web=info");
    emoji_logger::init();

    let result = HttpServer::new(move || {
        App::new()
            .wrap(Logger::default())
            .route("hello", web::get().to(hello_world))
            .route("data", web::post().to(receive_data))
    })
    .bind("0.0.0.0:8000")?
    .run()
    .await;

    println!("🧑‍🔬 Sample Service Stopping");

    result
}

We can double check this by running the service with cargo run, making some sample HTTP requests against it, and then checking the console output - it should show something like this:

🧑‍🔬 Sample Service Starting
😋 I  27.44  actix_web:logger > 127.0.0.1:61222 "GET /hello HTTP/1.1" 200 8 "-" "-" 0.000167
😋 I  95.19  actix_web:logger > 127.0.0.1:61416 "POST /data HTTP/1.1" 200 36 "-" "-" 0.000248
😋 I  125.96  actix_web:logger > 127.0.0.1:61506 "POST /data HTTP/1.1" 400 0 "-" "-" 0.000240
^C🧑‍🔬 Sample Service Stopping

Actix supports a bunch of different format options to configure what should be included in log messages if we wanted to change the output, but the default is good enough for now.