RESTful API Server

REST (Representational State Transfer) is an architectural style for designing networked applications. It defines a set of constraints for how clients and servers communicate, focusing on the manipulation of resources via a uniform interface. A RESTful API server adheres to these principles, making web services simple, scalable, and maintainable.

Core Principles of REST:
1. Client-Server Architecture: There's a clear separation of concerns between the client and the server. The client handles the user interface and user experience, while the server manages data storage, security, and business logic. This separation allows for independent evolution of both components.
2. Stateless: Each request from the client to the server must contain all the information necessary to understand the request. The server should not store any client context between requests. This improves scalability and reliability, as any server can handle any request.
3. Cacheable: Responses from the server can be labeled as cacheable or non-cacheable. Clients and intermediaries (proxies) can cache responses to improve performance and network efficiency for subsequent equivalent requests.
4. Layered System: A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way. This allows for intermediaries like load balancers, proxies, and security layers to be introduced or removed without affecting the client or the server.
5. Uniform Interface: This is the most crucial constraint, simplifying the overall system architecture by ensuring a standardized way of interacting with resources. It consists of four sub-constraints:
* Identification of Resources: Individual resources are identified in requests, for example, using Uniform Resource Identifiers (URIs).
* Manipulation of Resources Through Representations: Clients interact with resources by exchanging representations of those resources (e.g., JSON, XML). The representation contains enough information to allow the client to modify or delete the resource on the server, provided it has the necessary permissions.
* Self-descriptive Messages: Each message includes enough information to describe how to process the message. For example, HTTP headers provide context about the request or response (e.g., `Content-Type`).
* Hypermedia as the Engine of Application State (HATEOAS): The client interacts with the application entirely through hypermedia provided dynamically by the server. This means that responses should include links to related resources or actions the client can take. While fundamental to true REST, it's often the least strictly implemented aspect in many "REST-like" APIs.

How REST Applies to APIs:
* Resources: In a RESTful API, everything is treated as a resource. These resources are identified by URIs (e.g., `/users`, `/products/123`).
* HTTP Methods: Standard HTTP methods are used to perform operations on these resources, mapping closely to CRUD (Create, Read, Update, Delete) operations:
* `GET`: Retrieve a resource or a collection of resources. (Read)
* `POST`: Create a new resource, or submit data that requires processing. (Create)
* `PUT`: Update an existing resource or replace a resource entirely. (Update/Replace)
* `DELETE`: Remove a resource. (Delete)
* `PATCH`: Apply partial modifications to a resource. (Partial Update)
* Representations: Resources are typically represented using lightweight data formats like JSON (JavaScript Object Notation) or XML. JSON is predominant due to its simplicity and compatibility with web browsers.

Benefits of RESTful APIs:
* Simplicity: Uses standard HTTP methods and protocols, making it easy to understand and implement.
* Scalability: Statelessness and client-server separation allow for easy scaling of the server components.
* Flexibility: Clients and servers can be developed independently, and the server can easily change its underlying database or technology without affecting clients.
* Widespread Adoption: Due to its benefits, REST is the most common architectural style for web services, making it easy to find tools and libraries for development.

Example Code

```rust
use axum::{ 
    extract::{Path, State},
    http::StatusCode,
    response::IntoResponse,
    routing::{get, post, put, delete},
    Json,
    Router,
};
use serde::{Deserialize, Serialize};
use std::{
    collections::HashMap,
    sync::{Arc, Mutex},
};
use uuid::Uuid;

// 1. Define the Todo resource structure
#[derive(Debug, Clone, Serialize, Deserialize)]
struct Todo {
    id: Uuid,
    text: String,
    completed: bool,
}

// 2. Define the payload for creating a new Todo (ID is generated by server)
#[derive(Debug, Clone, Serialize, Deserialize)]
struct CreateTodoPayload {
    text: String,
}

// 3. Define the payload for updating an existing Todo
// Using Options allows for partial updates (e.g., update only 'text' or 'completed').
// For a strict PUT, the entire resource representation would typically be required.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
struct UpdateTodoPayload {
    text: Option<String>,
    completed: Option<bool>,
}

// 4. Shared application state: In-memory database using a HashMap.
// Arc<Mutex<...>> is used for thread-safe mutable access across asynchronous handlers.
type AppState = Arc<Mutex<HashMap<Uuid, Todo>>>;

#[tokio::main]
async fn main() {
    // Initialize the shared state
    let app_state = AppState::new(Mutex::new(HashMap::new()));

    // Build our application router, defining API endpoints and their HTTP methods.
    let app = Router::new()
        // Route for '/todos' supporting GET (read all) and POST (create new)
        .route("/todos", get(get_all_todos).post(create_todo))
        // Route for '/todos/:id' supporting GET (read one), PUT (update), and DELETE (delete one)
        .route("/todos/:id", get(get_todo_by_id).put(update_todo).delete(delete_todo))
        // Share the application state with all handlers
        .with_state(app_state);

    // Run our app with hyper, binding to a specific address and port
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
        .await
        .unwrap();
    println!("Listening on {}", listener.local_addr().unwrap());
    axum::serve(listener, app).await.unwrap();
}

// 5. Handler to get all todos (GET /todos)
async fn get_all_todos(
    State(state): State<AppState>, // Extract shared state
) -> Json<Vec<Todo>> {
    let todos_map = state.lock().unwrap(); // Acquire mutex lock
    let todos: Vec<Todo> = todos_map.values().cloned().collect(); // Collect all todos
    Json(todos) // Return as JSON array
}

// 6. Handler to create a new todo (POST /todos)
async fn create_todo(
    State(state): State<AppState>, // Extract shared state
    Json(payload): Json<CreateTodoPayload>, // Extract JSON payload from request body
) -> (StatusCode, Json<Todo>) {
    let mut todos_map = state.lock().unwrap(); // Acquire mutable mutex lock
    let new_todo = Todo {
        id: Uuid::new_v4(), // Generate a unique ID
        text: payload.text,
        completed: false,
    };
    todos_map.insert(new_todo.id, new_todo.clone()); // Insert new todo into the map
    (StatusCode::CREATED, Json(new_todo)) // Return 201 Created status and the new todo
}

// 7. Handler to get a todo by ID (GET /todos/:id)
async fn get_todo_by_id(
    State(state): State<AppState>, // Extract shared state
    Path(id): Path<Uuid>, // Extract 'id' from the URL path
) -> Result<Json<Todo>, StatusCode> {
    let todos_map = state.lock().unwrap();
    if let Some(todo) = todos_map.get(&id) { // Try to find the todo
        Ok(Json(todo.clone())) // Return 200 OK and the todo if found
    } else {
        Err(StatusCode::NOT_FOUND) // Return 404 Not Found if not found
    }
}

// 8. Handler to update a todo by ID (PUT /todos/:id)
async fn update_todo(
    State(state): State<AppState>, // Extract shared state
    Path(id): Path<Uuid>, // Extract 'id' from the URL path
    Json(payload): Json<UpdateTodoPayload>, // Extract JSON payload for update
) -> Result<Json<Todo>, StatusCode> {
    let mut todos_map = state.lock().unwrap();
    if let Some(todo) = todos_map.get_mut(&id) { // Get mutable reference to the todo
        if let Some(text) = payload.text { // Update text if provided in payload
            todo.text = text;
        }
        if let Some(completed) = payload.completed { // Update completed status if provided
            todo.completed = completed;
        }
        Ok(Json(todo.clone())) // Return 200 OK and the updated todo
    } else {
        Err(StatusCode::NOT_FOUND) // Return 404 Not Found if todo doesn't exist
    }
}

// 9. Handler to delete a todo by ID (DELETE /todos/:id)
async fn delete_todo(
    State(state): State<AppState>, // Extract shared state
    Path(id): Path<Uuid>, // Extract 'id' from the URL path
) -> Result<(), StatusCode> {
    let mut todos_map = state.lock().unwrap();
    if todos_map.remove(&id).is_some() { // Remove the todo from the map
        Ok(()) // Return 200 OK (no content) if deleted successfully
    } else {
        Err(StatusCode::NOT_FOUND) // Return 404 Not Found if todo doesn't exist
    }
}
```

To run this code:
1.  Create a new Rust project: `cargo new restful_api_server --bin`
2.  Navigate into the project directory: `cd restful_api_server`
3.  Add the necessary dependencies to your `Cargo.toml` file:
    ```toml
    [dependencies]
    axum = "0.7"
    tokio = { version = "1", features = ["full"] }
    serde = { version = "1", features = ["derive"] }
    uuid = { version = "1", features = ["serde", "v4"] }
    ```
4.  Replace the content of `src/main.rs` with the provided code.
5.  Run the server: `cargo run`

Example API Interactions (using `curl` in a new terminal):

*   Create a Todo:
    ```bash
    curl -X POST -H "Content-Type: application/json" -d '{"text":"Learn Rust REST APIs"}' http://127.0.0.1:3000/todos
    # Expected output: HTTP 201 Created with the new todo JSON, e.g., {"id":"...","text":"Learn Rust REST APIs","completed":false}
    ```

*   Get all Todos:
    ```bash
    curl http://127.0.0.1:3000/todos
    # Expected output: HTTP 200 OK with a JSON array of todos
    ```

*   Get a specific Todo (replace `YOUR_TODO_ID` with an ID from the POST response):
    ```bash
    curl http://127.0.0.1:3000/todos/YOUR_TODO_ID
    # Expected output: HTTP 200 OK with the specific todo JSON or 404 Not Found if ID is invalid
    ```

*   Update a Todo (replace `YOUR_TODO_ID`):
    ```bash
    curl -X PUT -H "Content-Type: application/json" -d '{"text":"Master Rust REST APIs", "completed":true}' http://127.0.0.1:3000/todos/YOUR_TODO_ID
    # Expected output: HTTP 200 OK with the updated todo JSON or 404 Not Found
    ```

*   Delete a Todo (replace `YOUR_TODO_ID`):
    ```bash
    curl -X DELETE http://127.0.0.1:3000/todos/YOUR_TODO_ID
    # Expected output: HTTP 200 OK (no body) if successful, or 404 Not Found
    ```

Example Code

Related Topics