Xata + Rust: A getting started guide.

This post discussed what Xata is and provided a detailed step-by-step guide to use it to build a project management API in Rust.

avatar

Demola Malomo

Feb 05 2024

7 min read

avatar

Xata is a serverless data platform for building modern and robust applications. Built on top of PostgreSQL, Xata provides a unified REST API for efficient data management. Setting itself apart from other data platforms, Xata introduces unique functionalities that significantly streamline the developer workflow. Here are some key benefits of integrating Xata into any application:

  • Robust file management: Xata provides APIs and SDKs to manage and securely upload images, documents, and more, directly to a database record.
  • Multiple environments support and workflow: With Xata, creating isolated production environments for testing, staging, or feature releases is seamless.
  • Fast search support: Xata automatically indexes uploaded data, facilitating fast and efficient data searches across tables and branches.
  • AI support: Xata offers vector embedding and AI solutions that empower the development of intelligent applications.

To experience the capabilities of Xata, we will build a project management API in Rust. This API will offer features for creating, reading, updating, and deleting (CRUD) projects. The project repository can be found here.

Prerequisites

To follow along with this tutorial, the following are needed:

  • Basic understanding of Rust
  • Xata account. Signup is free
  • Postman or any API testing application of your choice

Getting started

To get started, we need to navigate to the desired directory and run the command below:

cargo new rust-xata && cd rust-xata

This command creates a Rust project called rust-xata and navigates into the project directory.

Next, we install the required dependencies by modifying the [dependencies] section of the Cargo.toml file as shown below:

1[dependencies] 2actix-web = "4.4.1" 3serde = { version = "1.0.195", features = ["derive"] } 4serde_json = "1.0.111" 5dotenv = "0.15.0" 6reqwest = { version = "0.11.23", features = ["json"] }

actix-web = "4.4.1" is a Rust-based framework for building web applications.

serde = { version = "1.0.145", features = ["derive"] } for serializing and deserializing Rust data structures.

serde_json = "1.0" for manipulating JSON and vice versa.

reqwest = { version = "0.11", features = ["json"] } for making HTTP requests.

We need to run the command below to install the dependencies:

1cargo build

Structuring the application

It is essential to have a good project structure as it makes the codebase maintainable and seamless for anyone to read or manage.

To do this, we need to navigate to the src directory and, in this folder, create an api folder. In the api folder, we also need to create a mod.rs, models.rs, services.rs, and handlers.rs files.

mod.rs is a file for managing application visibility.

models.rs is for structuring our application data.

xata_services.rs is for abstracting our application logic.

handlers.rs is for structuring our APIs.

Next, we need to declare these files as a module by importing them into the mod.rs file

1pub mod handlers; 2pub mod models; 3pub mod services;

Finally, we need to register api folder as a parent module by importing it into the main.rs file as shown below:

1mod api; //add 2 3fn main() { 4 println!("Hello world") 5}

Setup the database on Xata

To get started, log into the Xata workspace and create a project database. Inside the project database, create a Project table and add columns as shown below:

Column typeColumn name
Stringname
Textdescription
Stringstatus

Create database Add table Add field

Inside a table, Xata automatically adds an id, xata.createdAt, xata.updatedAt, and xata.version columns that we can also leverage to perform advanced data operations.

Created column

Get the Database URL and set up the API Key

To securely connect to the database, Xata provides a unique and secure URL for accessing it. To get the database URL, click the Get code snippet button and copy the URL. Then click the API Key link, add a new key, save and copy the API key.

click the Get code snippet button copy URL create API key

Setup environment variable

Next, we must add our database URL and API key as an environment variable. To do this, create .env file in the root directory and add the copied URL and API key.

1XATA_DATABASE_URL= <REPLACE WITH THE COPIED DATABASE URL> 2XATA_API_KEY=<REPLACE WITH THE COPIED API KEY>

Building the project management API with Rust and Xata

We can start building our API with our database fully set up on Xata and a secure URL created to access it.

Create the API models

To represent the application data, we need to update the models.rs file as shown below:

1use serde::{Deserialize, Serialize}; 2 3#[derive(Deserialize, Serialize, Debug, Clone)] 4pub struct Project { 5 pub id: String, 6 pub name: String, 7 pub description: String, 8 pub status: String, 9} 10 11#[derive(Deserialize, Serialize, Debug, Clone)] 12pub struct ProjectRequest { 13 pub name: String, 14 pub description: String, 15 pub status: String, 16} 17 18#[derive(Deserialize, Serialize, Debug, Clone)] 19pub struct ProjectResponse { 20 pub id: String, 21} 22 23#[derive(Serialize, Debug, Clone)] 24pub struct APIResponse<T> { 25 pub status: u16, 26 pub message: String, 27 pub data: Option<T>, 28} 29 30#[derive(Serialize, Debug, Clone)] 31pub struct APIErrorResponse { 32 pub status: u16, 33 pub message: String, 34 pub data: Option<String>, 35}

The snippet above does the following:

  • Imports the required dependency
  • Creates a Project, ProjectRequest, and ProjectResponse structs with required properties to describe request and response body accordingly
  • Creates an APIResponse, and APIErrorResponse structs with the required properties needed for the API response

Create the API services

With our application models fully set up, we can now use them to create our application logic. To do this, we need to update the xata_service.rs file by doing the following:

First, we need to import the required dependencies and create helper functions:

1use std::env; 2use dotenv::dotenv; 3use reqwest::{header, Client, Error, RequestBuilder}; 4use super::model::{Project, ProjectRequest, ProjectResponse}; 5 6pub struct XataService; 7 8impl XataService { 9 fn env_loader(key: &str) -> String { 10 dotenv().ok(); 11 match env::var(key) { 12 Ok(v) => v.to_string(), 13 Err(_) => format!("Error loading env variable"), 14 } 15 } 16 17 fn init() -> Client { 18 Client::new() 19 } 20 21 fn create_headers() -> header::HeaderMap { 22 let mut headers = header::HeaderMap::new(); 23 headers.insert("Content-Type", "application/json".parse().unwrap()); 24 headers.insert( 25 header::AUTHORIZATION, 26 format!("Bearer {}", XataService::env_loader("XATA_API_KEY")) 27 .parse() 28 .unwrap(), 29 ); 30 headers 31 } 32 33 async fn send_request(builder: RequestBuilder) -> Result<reqwest::Response, reqwest::Error> { 34 builder.send().await 35 } 36 37 async fn handle_response<T>(response: reqwest::Response) -> Result<T, reqwest::Error> 38 where 39 T: serde::de::DeserializeOwned, 40 { 41 let json = response.text().await?; 42 Ok(serde_json::from_str(json.as_str()).unwrap()) 43 } 44}

The snippet above does the following:

  • Imports the required dependencies
  • Creates an XataService struct
  • Creates an implementation block that adds env_loader, init, create_headers, send_request, and handle_response helper methods. These methods are designed to load environment variables, create a connection pool for making asynchronous requests, generate request headers, handle the sending of requests, and manage the deserialization of JSON responses.

Lastly, we need to add methods that use the helper methods to perform CRUD operations.

1//imports goes here 2 3pub struct XataService; 4 5impl XataService { 6 //helper methodes goes here 7 8 pub async fn create_project(new_project: ProjectRequest) -> Result<ProjectResponse, Error> { 9 let url = format!( 10 "{}:main/tables/Project/data", 11 XataService::env_loader("XATA_DATABASE_URL") 12 ); 13 14 let client = XataService::init() 15 .post(url) 16 .headers(XataService::create_headers()) 17 .json(&new_project); 18 19 let response = XataService::send_request(client).await?; 20 XataService::handle_response(response).await 21 } 22 23 pub async fn get_project(project_id: String) -> Result<Project, Error> { 24 let url = format!( 25 "{}:main/tables/Project/data/{}", 26 XataService::env_loader("XATA_DATABASE_URL"), 27 project_id 28 ); 29 30 let client = XataService::init() 31 .get(url) 32 .headers(XataService::create_headers()); 33 34 let response = XataService::send_request(client).await?; 35 XataService::handle_response(response).await 36 } 37 38 pub async fn update_project( 39 updated_project: ProjectRequest, 40 project_id: String, 41 ) -> Result<ProjectResponse, Error> { 42 let url = format!( 43 "{}:main/tables/Project/data/{}", 44 XataService::env_loader("XATA_DATABASE_URL"), 45 project_id 46 ); 47 48 let client = XataService::init() 49 .put(url) 50 .headers(XataService::create_headers()) 51 .json(&updated_project); 52 53 let response = XataService::send_request(client).await?; 54 XataService::handle_response(response).await 55 } 56 57 pub async fn delete_project(project_id: String) -> Result<String, Error> { 58 let url = format!( 59 "{}:main/tables/Project/data/{}", 60 XataService::env_loader("XATA_DATABASE_URL"), 61 project_id 62 ); 63 64 let client = XataService::init() 65 .delete(url) 66 .headers(XataService::create_headers()); 67 68 let _response = XataService::send_request(client).await?; 69 Ok(format!( 70 "Project with ID: {} deleted successfully!!", 71 project_id 72 )) 73 } 74}

The snippet above creates a create_project, get_project, update_project, and delete_project methods for performing CRUD operations.

Create the API handlers

With that done, we can use the services to create our API handlers. To do this, first, we need to add the snippet below to the handlers.rs file:

1use actix_web::{ 2 delete, get, post, put, 3 web::{Json, Path}, 4 HttpResponse, 5}; 6use reqwest::StatusCode; 7use super::{ 8 model::{APIErrorResponse, APIResponse, Project, ProjectRequest, ProjectResponse}, 9 xata_service::XataService, 10}; 11 12#[post("/project")] 13pub async fn create_project_handler(new_project: Json<ProjectRequest>) -> HttpResponse { 14 let project_details = XataService::create_project(new_project.to_owned()).await; 15 16 match project_details { 17 Ok(data) => HttpResponse::Accepted().json(APIResponse::<ProjectResponse> { 18 status: StatusCode::CREATED.as_u16(), 19 message: "success".to_string(), 20 data: Some(data), 21 }), 22 Err(error) => HttpResponse::InternalServerError().json(APIErrorResponse { 23 status: StatusCode::INTERNAL_SERVER_ERROR.as_u16(), 24 message: "failure".to_string(), 25 data: Some(error.to_string()), 26 }), 27 } 28} 29 30#[get("/project/{id}")] 31pub async fn get_project_handler(path: Path<String>) -> HttpResponse { 32 let id = path.into_inner(); 33 if id.is_empty() { 34 return HttpResponse::BadRequest().json(APIErrorResponse { 35 status: StatusCode::BAD_REQUEST.as_u16(), 36 message: "failure".to_string(), 37 data: Some("invalid ID".to_string()), 38 }); 39 }; 40 41 let project_details = XataService::get_project(id).await; 42 43 match project_details { 44 Ok(data) => HttpResponse::Accepted().json(APIResponse::<Project> { 45 status: StatusCode::OK.as_u16(), 46 message: "success".to_string(), 47 data: Some(data), 48 }), 49 Err(error) => HttpResponse::InternalServerError().json(APIErrorResponse { 50 status: StatusCode::INTERNAL_SERVER_ERROR.as_u16(), 51 message: "failure".to_string(), 52 data: Some(error.to_string()), 53 }), 54 } 55}

The snippet above does the following:

  • Imports the required dependencies
  • Creates a create_project_handler and get_project_handler handler with corresponding API routes that use the services to perform the corresponding actions and return the appropriate response using the APIResponse and APIErrorResponse

Lastly, we need to add update_project_handler and delete_project_handler handlers that use logic similar to the handlers above to update and delete a project.

1//imports goes here 2 3#[post("/project")] 4pub async fn create_project_handler(new_project: Json<ProjectRequest>) -> HttpResponse { 5 //create_project_handler code goes here 6} 7 8#[get("/project/{id}")] 9pub async fn get_project_handler(path: Path<String>) -> HttpResponse { 10 //get_project_handler code goes here 11} 12 13#[put("/project/{id}")] 14pub async fn update_project_handler( 15 updated_project: Json<ProjectRequest>, 16 path: Path<String>, 17) -> HttpResponse { 18 let id = path.into_inner(); 19 if id.is_empty() { 20 return HttpResponse::BadRequest().json(APIErrorResponse { 21 status: StatusCode::BAD_REQUEST.as_u16(), 22 message: "failure".to_string(), 23 data: Some("invalid ID".to_string()), 24 }); 25 }; 26 27 let project_details = XataService::update_project(updated_project.to_owned(), id).await; 28 29 match project_details { 30 Ok(data) => HttpResponse::Accepted().json(APIResponse::<ProjectResponse> { 31 status: StatusCode::OK.as_u16(), 32 message: "success".to_string(), 33 data: Some(data), 34 }), 35 Err(error) => HttpResponse::InternalServerError().json(APIErrorResponse { 36 status: StatusCode::INTERNAL_SERVER_ERROR.as_u16(), 37 message: "failure".to_string(), 38 data: Some(error.to_string()), 39 }), 40 } 41} 42 43#[delete("/project/{id}")] 44pub async fn delete_project_handler(path: Path<String>) -> HttpResponse { 45 let id = path.into_inner(); 46 if id.is_empty() { 47 return HttpResponse::BadRequest().json(APIErrorResponse { 48 status: StatusCode::BAD_REQUEST.as_u16(), 49 message: "failure".to_string(), 50 data: Some("invalid ID".to_string()), 51 }); 52 }; 53 54 let project_details = XataService::delete_project(id).await; 55 56 match project_details { 57 Ok(data) => HttpResponse::Accepted().json(APIResponse::<String> { 58 status: StatusCode::ACCEPTED.as_u16(), 59 message: "success".to_string(), 60 data: Some(data), 61 }), 62 Err(error) => HttpResponse::InternalServerError().json(APIErrorResponse { 63 status: StatusCode::INTERNAL_SERVER_ERROR.as_u16(), 64 message: "failure".to_string(), 65 data: Some(error.to_string()), 66 }), 67 } 68}

Putting it all together

With that done, we must update the main.rs file to include our application entry point and use the handlers.

1use actix_web::{App, HttpServer}; 2use api::handler::{ 3 create_project_handler, delete_project_handler, get_project_handler, update_project_handler, 4}; 5mod api; 6 7#[actix_web::main] 8async fn main() -> std::io::Result<()> { 9 HttpServer::new(move || { 10 App::new() 11 .service(create_project_handler) 12 .service(get_project_handler) 13 .service(update_project_handler) 14 .service(delete_project_handler) 15 }) 16 .bind(("localhost", 8080))? 17 .run() 18 .await 19}

The snippet above does the following:

  • Imports the required dependencies
  • Creates a new server that adds the handlers and runs on localhost:8080

With that done, we can start a development server using the command below:

1cargo run main

Create project Get a project Update a project

Delete a project

We can also confirm the project management data by checking the table on Xata.

Data on Xata

Conclusion

This post discussed what Xata is and provided a detailed step-by-step guide to use it to build a project management API in Rust. In addition to the functionalities explored earlier, Xata also includes well-tailored features that developers can harness to build applications ranging from small to large.

These resources may also be helpful:

Related posts